# Channel `Channel` is the main entry point for customization and hosts most of the contexts and logic used by the React Native SDK. [MessageList](/chat/docs/sdk/react-native/v8/ui-components/message-list/), [MessageInput](/chat/docs/sdk/react-native/v8/ui-components/message-input/), and [Thread](/chat/docs/sdk/react-native/v8/ui-components/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](/chat/docs/javascript/creating_channels/) or read it from [`ChannelList`](/chat/docs/sdk/react-native/v8/core-components/channel-list/) via the [`onSelect`](/chat/docs/sdk/react-native/v8/core-components/channel-list#required-onselect/) callback. ```tsx {7-17,22,25} 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 ( ); }; ``` ## Context Providers `Channel` provides `ChannelContext`, `KeyboardContext`, `MessageInputContext`, `MessagesContext`, `PaginatedMessageListContext`, `AttachmentPickerContext`, `MessageComposerContext`, `ThreadContext`, and `TypingContext` via their hooks. | Context | Hook | | ----------------------------- | -------------------------------- | | `ChannelContext` | `useChannelContext` | | `KeyboardContext` | `useKeyboardContext` | | `MessageInputContext` | `useMessageInputContext` | | `MessagesContext` | `useMessagesContext` | | `PaginatedMessageListContext` | `usePaginatedMessageListContext` | | `AttachmentPickerContext` | `useAttachmentPickerContext` | | `MessageComposerContext` | `useMessageComposerAPIContext` | | `ThreadContext` | `useThreadContext` | | `TypingContext` | `useTypingContext` | ## 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. ```tsx import { Image } from "react-native"; import { Channel, useMessageContext } from "stream-chat-react-native"; const CustomAvatar = () => { const { message } = useMessageContext(); return ; }; ; ``` ![](@chat-sdk/react-native/v8/_assets/ui-components/channel/visual_guide_1.png) ![](@chat-sdk/react-native/v8/_assets/ui-components/channel/visual_guide_2.png) ![](@chat-sdk/react-native/v8/_assets/ui-components/channel/visual_guide_3.png) ![](@chat-sdk/react-native/v8/_assets/ui-components/channel/visual_guide_4.png) ## Props ### channel Channel instance from the Stream Chat client. | Type | | --------------------------------------------------- | | [Channel](/chat/docs/javascript/creating_channels/) | ### keyboardVerticalOffset Distance from the top of the screen to the top of the `Channel` component (often your header height). | Type | | ------ | | number | ### additionalKeyboardAvoidingViewProps Extra props passed to [KeyboardAvoidingView](https://reactnative.dev/docs/keyboardavoidingview#props). | Type | | ------ | | Object | ### additionalTextInputProps Extra props passed to the underlying [TextInput](https://reactnative.dev/docs/textinput#props) in [`MessageInput`](/chat/docs/sdk/react-native/v8/ui-components/message-input/). | Type | | ------ | | object | ### additionalPressableProps Extra props passed to the underlying [Pressable](https://reactnative.dev/docs/pressable#props) used in message components like [`MessageContent`](/chat/docs/sdk/react-native/v8/ui-components/message-content/). | Type | | ------ | | object | ### allowConcurrentAudioPlayback Allow multiple audio players to play at once. Disabled by default. Available since v8.9.0. | Type | | ------- | | Boolean | ### allowThreadMessagesInChannel Show the _Show thread message in channel_ button in thread `MessageInput`. | Type | Default | | ------- | ------- | | boolean | true | ### asyncMessagesLockDistance Pixels the user must drag upward to lock recording and lift their finger without stopping it. | Type | Default | | ------ | ------- | | Number | 50 | ### asyncMessagesMinimumPressDuration Minimum press duration (ms) on the record button to start voice recording. | Type | Default | | ------ | ------- | | Number | 500 | ### asyncMessagesMultiSendEnabled When enabled, recordings don’t send immediately. They stack in the composer so users can send multiple voice recordings in one message. | Type | Default | | ------- | ------- | | Boolean | true | ### asyncMessagesSlideToCancelDistance Pixels the user must drag toward the leading side to cancel voice recording. | Type | Default | | ------ | ------- | | Number | 100 | ### audioRecordingEnabled Enable or disable audio recording. | Type | Default | | ------- | ------- | | Boolean | false | ### attachmentPickerErrorText Error text for [`AttachmentPickerError`](https://github.com/GetStream/stream-chat-react-native/v8/blob/develop/package/src/components/AttachmentPicker/components/AttachmentPickerError.tsx). | Type | Default | | ------ | ----------------------------------------------------------------------- | | String | "Please enable access to your photos and videos so you can share them." | ### attachmentPickerErrorButtonText Button text in [`AttachmentPickerError`](https://github.com/GetStream/stream-chat-react-native/v8/blob/develop/package/src/components/AttachmentPicker/components/AttachmentPickerError.tsx) that opens the app’s OS settings. | Type | Default | | ------ | ------------------------------ | | String | "Allow access to your Gallery" | ### attachmentPickerBottomSheetHeight Height of the attachment picker bottom sheet when open. | Type | Default | | ------ | -------------------- | | Number | 40% of Window Height | ### attachmentSelectionBarHeight Height of the attachment selection bar in the attachment picker. | Type | Default | | ------ | ------- | | Number | 52 | ### attachmentPickerBottomSheetHandleHeight Height of the attachment picker bottom sheet handle. | Type | Default | | ------ | ------- | | Number | 20 | ### bottomInset Height of items located below the `MessageInput` when present. This inset determines the underlying shift to the `MessageList` when it is opened. This can also be set via the `setBottomInset` function provided by the `useAttachmentPickerContext` hook. | Type | Default | | ------ | ------- | | Number | 0 | ### compressImageQuality Image compression quality before upload. On iOS, values >= 0.8 usually keep quality while reducing size. A value of 0.8 can roughly halve file size vs 1.0. | Type | Default | | --------------------------------- | -------------------- | | number 0 to 1 (1 is best quality) | iOS: 0.8, Android: 1 | ### customMessageSwipeAction Custom action executed when the user swipes a message. | Type | Default | | ------------------------------------------------------------------------- | ------------------------------------- | | `({channel, message}: {channel: Channel, message: LocalMessage}) => void` | The default action is swipe to reply. | ### 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. | Type | Default | | --------------------------------------------- | ------- | | enum('always', 'never', 'receiver', 'sender') | 'both' | ### disableKeyboardCompatibleView Enable or disable the underlying [KeyboardAvoidingView](https://reactnative.dev/docs/keyboardavoidingview#enabled). | Type | Default | | ------- | ------- | | boolean | false | ### disableTypingIndicator Disable the typing indicator in `MessageList`. | Type | Default | | ------- | ------- | | boolean | false | ### dismissKeyboardOnMessageTouch Dismiss the keyboard when the user touches a message in the list. | Type | Default | | ------- | ------- | | boolean | false | ### doFileUploadRequest Override the file upload request when a user selects a file. Must return a `Promise`. Use this to store files in your own CDN. | Type | | -------- | | Function | This matches the definition of `UploadRequestFn` from the `stream-chat` package. ```ts export type UploadRequestFn = ( fileLike: FileReference | FileLike, ) => Promise; ``` ### doMarkReadRequest Override the mark read request. This prop should only be used for advanced functionality in which you want to conditionally allow mark-read requests. Do not use this function to disable read receipts. If you would like to disable read-receipts, this can be done via _Read Events_ on the dashboard. #### Example ```tsx const doMarkReadRequest = (channel) => { if (/** Some custom logic here */) { channel.markRead(); } }; ``` | Type | | -------- | | Function | | Parameter | Description | | ---------------------------------------- | ---------------- | | `channel` | channel instance | | `setChannelUnreadUiState` \| `undefined` | `(state) =>void` | ### doSendMessageRequest Override the send message request. This function must return a Promise equivalent to `client.sendMessage`. Use this only if you need to alter the message object before sending. #### Example ```tsx const doSendMessageRequest = (channelId, messageObject) => { if (/** Some custom logic here */) { messageObject.isSpecial = true; } return channel.sendMessage(messageObject); } ``` | Type | | -------- | | function | | Parameter | Description | | ------------- | ------------------- | | channelId | string | | messageObject | object | | options | object \| undefined | ### doUpdateMessageRequest Override the update message request. This function must return a Promise equivalent to `client.updateMessage`. Use this only if you need to alter the message object before updating. ```tsx const doUpdateMessageRequest = (channelId, messageObject) => { const numberOfUpdates = (messageObject.numberOfUpdates ?? 0) + 1; const messageToSend = { ...messageObject, numberOfUpdates }; return client.updateMessage(messageToSend); }; ``` | Type | | -------- | | function | | Parameter | Description | | ------------- | ------------------- | | channelId | string | | messageObject | object | | options | object \| undefined | ### enableMessageGroupingByUser **Note:** Available in SDK version >= [v3.9.0](https://github.com/GetStream/stream-chat-react-native/v8/releases). If false, consecutive messages from the same user won’t be grouped. | Type | Default | | ------- | ------- | | boolean | true | ### enableSwipeToReply If true, users can swipe to reply to a message. | Type | Default | | ------- | ------- | | Boolean | `true` | ### enforceUniqueReaction Limits reactions to one per user. Selecting a new reaction replaces the previous one (similar to iMessage). | Type | Default | | ------- | ------- | | boolean | false | ### forceAlignMessages Forces all messages to align left or right. By default, received messages are left and sent messages are right. | Type | Default | | -------------------------- | ------- | | 'left' \| 'right' \| false | false | ### `formatDate` Format function for dates in message status and deleted message components. | Type | | -------- | | function | | Parameter | Description | | --------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- | | date | date to format provided as a string, [Date](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date), or number (Unix Timestamp) | ### 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`](https://github.com/GetStream/stream-chat-react-native/v8/blob/develop/package/src/components/MessageList/utils/getGroupStyles.ts). Access the computed styles via `MessageContext.groupStyles` in custom components. | Type | | -------- | | function | ### 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+`. | Type | Default | | ------ | ------- | | number | 255 | ### giphyVersion Giphy image version to render. See the [Image Object](https://developers.giphy.com/docs/api/schema#image-object) keys for options. | Type | Default | | ------ | -------------- | | string | 'fixed_height' | ### `handleAttachButtonPress` Customize behavior when the [AttachButton](/chat/docs/sdk/react-native/v8/ui-components/attach-button/) is pressed in the message input. | Type | | ------------ | | `() => void` | ### `handleBan` Called when the _Ban User_ action is triggered. It does not override default behavior. See [customize message actions](/chat/docs/sdk/react-native/v8/guides/customize-message-actions/). | Type | | -------- | | function | | Parameter | Description | | --------- | ------------------------------- | | message | message the action is called on | ### `handleCopy` Called when the _Copy Message_ action is triggered. It does not override default behavior. See [customize message actions](/chat/docs/sdk/react-native/v8/guides/customize-message-actions/). | Type | | -------- | | function | | Parameter | Description | | --------- | ------------------------------- | | message | message the action is called on | ### `handleDelete` Called when the _Delete Message_ action is triggered. It does not override default behavior. See [customize message actions](/chat/docs/sdk/react-native/v8/guides/customize-message-actions/). | Type | | -------- | | function | | Parameter | Description | | --------- | ------------------------------- | | message | message the action is called on | ### `handleDeleteForMe` Called when the _Delete Message for me_ action is triggered. It does not override default behavior. See [customize message actions](/chat/docs/sdk/react-native/v8/guides/customize-message-actions/). | Type | | -------- | | function | | Parameter | Description | | --------- | ------------------------------- | | message | message the action is called on | ### `handleEdit` Called when the _Edit Message_ action is triggered. It does not override default behavior. See [customize message actions](/chat/docs/sdk/react-native/v8/guides/customize-message-actions/). | Type | | -------- | | function | | Parameter | Description | | --------- | ------------------------------- | | message | message the action is called on | ### `handleFlag` Called when the _Flag Message_ action is triggered. It does not override default behavior. See [customize message actions](/chat/docs/sdk/react-native/v8/guides/customize-message-actions/). | Type | | -------- | | function | | Parameter | Description | | --------- | ------------------------------- | | message | message the action is called on | ### `handleMarkUnread` Called when the _Mark Unread_ action is triggered. It does not override default behavior. See [customize message actions](/chat/docs/sdk/react-native/v8/guides/customize-message-actions/). | Type | | -------- | | function | | Parameter | Description | | --------- | ------------------------------- | | message | message the action is called on | ### `handleMute` Called when the _Mute User_ action is triggered from the message actions list. It does not override default behavior. See [customize message actions](/chat/docs/sdk/react-native/v8/guides/customize-message-actions/). | Type | | -------- | | function | | Parameter | Description | | --------- | ------------------------------- | | message | message the action is called on | ### handlePinMessage Called when the _Pin to Conversation_ or _Unpin from Conversation_ action is triggered. It does not override default behavior. See [customize message actions](/chat/docs/sdk/react-native/v8/guides/customize-message-actions/). | Type | | -------- | | function | | Parameter | Description | | --------- | ------------------------------- | | message | message the action is called on | ### handleReaction Called when a reaction is selected in the message menu (add or remove). It does not override default behavior. See [customize message actions](/chat/docs/sdk/react-native/v8/guides/customize-message-actions/). | Type | | -------- | | Function | | Parameter | Description | | -------------- | ---------------------------------------- | | `message` | Message the action is called on. | | `reactionType` | String designating the type of reaction. | ### handleQuotedReply Called when the _Reply_ action is triggered. It does not override default behavior. See [customize message actions](/chat/docs/sdk/react-native/v8/guides/customize-message-actions/). | Type | | -------- | | function | | Parameter | Description | | --------- | ------------------------------- | | message | message the action is called on | ### `handleRetry` Called when the _Retry_ action is triggered. It does not override default behavior. See [customize message actions](/chat/docs/sdk/react-native/v8/guides/customize-message-actions/). | Type | | -------- | | function | | Parameter | Description | | --------- | ------------------------------- | | message | message the action is called on | ### handleThreadReply Called when the _Thread Reply_ action is triggered. It does not override default behavior. See [customize message actions](/chat/docs/sdk/react-native/v8/guides/customize-message-actions/). | Type | | -------- | | function | | Parameter | Description | | --------- | ------------------------------- | | message | message the action is called on | ### `hasCameraPicker` Enable the camera picker in [`MessageInput`](/chat/docs/sdk/react-native/v8/ui-components/message-input/). | Type | Default | | ------- | ------- | | Boolean | `true` | ### `hasCommands` Enable commands in [`MessageInput`](/chat/docs/sdk/react-native/v8/ui-components/message-input/). | Type | Default | | ------- | ------- | | boolean | true | ### hasFilePicker Enable the file picker in [`MessageInput`](/chat/docs/sdk/react-native/v8/ui-components/message-input/). | Type | Default | | ------- | ------- | | Boolean | `true` | ### hasImagePicker Enable the image picker in [`MessageInput`](/chat/docs/sdk/react-native/v8/ui-components/message-input/). | Type | Default | | ------- | ------- | | Boolean | `true` | ### hideDateSeparators Hide inline date separators in [`MessageList`](/chat/docs/sdk/react-native/v8/ui-components/message-list/). | Type | Default | | ------- | ------- | | boolean | false | ### hideStickyDateHeader **Note:** Available in SDK version >= [v3.9.0](https://github.com/GetStream/stream-chat-react-native/v8/releases). Hide the sticky date header in [`MessageList`](/chat/docs/sdk/react-native/v8/ui-components/message-list/). | Type | Default | | ------- | ------- | | boolean | false | ### initialScrollToFirstUnreadMessage Load the channel starting at the first unread message. | Type | Default | | ------- | ------- | | boolean | false | ### isAttachmentEqual Returns true if rendering `nextAttachment` would produce the same result as `prevAttachment`, otherwise false. | Type | | -------- | | function | | Parameter | Description | | -------------- | ------------------------------------------ | | prevAttachment | previous message attachment to be compared | | nextAttachment | next message attachment to be compared | ### `keyboardBehavior` Behavior for the keyboard passed to the underlying [KeyboardAvoidingView](https://reactnative.dev/docs/keyboardavoidingview#behavior). | Type | | ----------------------------------- | | 'height' \| 'position' \| 'padding' | ### legacyImageViewerSwipeBehaviour **Note:** Available in SDK version >= [v3.9.0](https://github.com/GetStream/stream-chat-react-native/v8/releases). 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. | Type | Default | | ------- | ------- | | boolean | false | ### `loadingMore` Override the `loadingMore` value supplied by the channel query logic. | Type | | ------- | | Boolean | ### `loadingMoreRecent` Override the `loadingMoreRecent` value supplied by the channel query logic. | Type | | ------- | | Boolean | ### markdownRules Rules for [simple-markdown](https://github.com/Khan/simple-markdown#adding-a-simple-extension). | Type | | ------ | | object | ### `markReadOnMount` Enable/disable marking the channel as read when `Channel` mounts. | Type | | ------- | | Boolean | ### maxMessageLength Maximum message length. The default comes from the [channel config](/chat/docs/javascript/channel_features/). | Type | | ------ | | number | ### maxTimeBetweenGroupedMessages Maximum time (ms) between consecutive messages from the same user to keep them grouped. | Type | Default | | ------ | -------- | | number | infinite | ### `messageId` Load the channel at a specified message instead of the most recent message. | Type | | ------ | | string | ### `messageActions` An array of actions, or a function returning an array, shown in the message menu. See [customize message actions](/chat/docs/sdk/react-native/v8/guides/customize-message-actions/). | Type | Default | | ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------- | | Array \| Function | [messageActions](https://github.com/GetStream/stream-chat-react-native/v8/blob/main/package/src/components/Message/utils/messageActions.ts) | | Parameter | Description | | ------------ | ------------------------------------------------------------------- | | `actionInfo` | An object containing the original actions and relevant message data | ### messageContentOrder Order for rendering message content. | Type | Default | | ----- | ----------------------------------------------------------- | | array | ['quoted_reply', 'gallery', 'files', 'text', 'attachments'] | ### messageSwipeToReplyHitSlop Defines the `hitSlop` area for the message swipe-to-reply gesture. | Type | Default | | -------------------------------------------------------------------- | ----------------------------------------- | | Object`{ top: number, left: number, bottom: number, right: number }` | `{left: screenWidth, right: screenWidth}` | ### `messageTextNumberOfLines` Number of lines for message text in the Message Overlay. | Type | Default | | ------ | ------- | | number | 5 | ### myMessageTheme [Theme](/chat/docs/sdk/react-native/v8/customization/theming/) applied to the current user’s messages. | Type | | ------ | | object | Memoize this object or pass a stable reference. ### newMessageStateUpdateThrottleInterval **Note:** Available in SDK version >= [v3.9.0](https://github.com/GetStream/stream-chat-react-native/v8/releases). 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. | Type | Default | | ------ | ------- | | number | 500 | ### numberOfLines Maximum number of lines the underlying [`TextInput`](https://reactnative.dev/docs/textinput) in [`MessageInput`](/chat/docs/sdk/react-native/v8/ui-components/message-input/) can expand to. | Type | Default | | ------ | ------- | | number | 5 | ### numberOfAttachmentImagesToLoadPerCall Number of images loaded per `CameraRoll.getPhotos` call. | Type | Default | | ------ | ------- | | Number | 60 | ### numberOfAttachmentPickerImageColumns Number of columns in the image picker. | Type | Default | | ------ | ------- | | Number | 3 | ### onLongPressMessage Called when a user long-presses a message. The default opens the message menu. | Type | | -------- | | function | | Parameter | Description | | --------- | ----------------------------- | | payload | `{ actionHandlers, message }` | ### onPressMessage Called when a user presses a message. The default handler behaves differently for reactions and attachments. Handle those cases if you override it. | Type | | -------- | | function | | Parameter | Description | | --------- | --------------------------------------------- | | payload | `{ additionalInfo, actionHandlers, message }` | `additionalInfo` provides extra data for certain emitters (for example, user details for `textMention`). For example: ```tsx { 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?.(); }} > ``` `additionalInfo` may change as we add more emitter use cases. ### onPressInMessage Called on touch start, before [`onPressMessage`](#onpressmessage). | Type | | -------- | | function | | Parameter | Description | | --------- | ----------------------------- | | payload | `{ actionHandlers, message }` | ### 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: ```tsx