Channel

The Channel component is a React Context provider that wraps all the logic, functionality, and UI for an individual chat channel. It provides five separate contexts to its children:

• ChannelStateContext - stateful data (ex: messages or members)
• ChannelActionContext - action handlers (ex: sendMessage or openThread)
• ComponentContext - custom component UI overrides (ex: Avatar or Message)
• TypingContext - object of currently typing users (i.e., typing)

note

The Channel component renders an individual channel object. For detailed information regarding channel objects and their functionality, check out the JavaScript docs on our website.

Basic Usage

The Channel component does not inject any UI, so its implementation is fairly simple and can be handled in one of two ways, both with and without a ChannelList component. If you are using a ChannelList, do not add a channel object as a prop on Channel. However, in the absence of a ChannelList, the channel prop is required. By default, the ChannelList sets the active channel object, which is then injected it into the ChannelStateContext, so manual prop passing is not required.

Example 1 - without ChannelList

<Chat client={client}>
  <Channel channel={channel}>
    <MessageList />
    <MessageInput />
  </Channel>
</Chat>

Example 2 - with ChannelList

<Chat client={client}>
  <ChannelList />
  <Channel>
    <MessageList />
    <MessageInput />
  </Channel>
</Chat>

Any child of the Channel component has access to the contexts referenced above. Each context can be accessed with one of our custom hooks, which must be imported individually.

const { messages } = useChannelStateContext();
const { sendMessage } = useChannelActionContext();
const { Avatar } = useComponentContext();
const { typing } = useTypingContext();

Registering custom components

In case you would like to customize parts of your chat application, you can do that by passing custom components to Channel component props. All the title-cased props are reserved for the custom components overriding the SDK defaults. The list of all customizable components - the component context - can be found in the ComponentContext documentation.

Example of registering custom Avatar component

import { Channel, ChannelList, Chat, MessageInput, MessageList } from 'stream-chat-react';
import { CustomTooltip } from '../Tooltip/CustomTooltip';

const Avatar = ({ image, title }) => {
  return (
    <>
      <CustomTooltip>{title}</CustomTooltip>
      <div className='avatar-image'>
        <img src={image} alt={title} />
      </div>
    </>
  );
};

export const App = (
  <Chat client={client}>
    <ChannelList />
    <Channel Avatar={Avatar}>
      <MessageList />
      <MessageInput />
    </Channel>
  </Chat>
);

Props

channel

The currently active StreamChat channel instance to be loaded into the Channel component and referenced by its children.

const channel = client.channel('messaging', {
  members: ['nate', 'roy'],
});

caution

Do not provide this prop if you are using the ChannelList component, as it handles channel setting logic.

Type
object

acceptedFiles

A list of accepted file upload types.

Type
string[]

activeUnreadHandler

Custom handler function that runs when the active channel has unread messages and the app is running on a separate browser tab.

Type
(unread: number, documentTitle: string) => void

Attachment

Custom UI component to display a message attachment.

Type	Default
component	Attachment

AttachmentPreviewList

Custom UI component to display an attachment previews in MessageInput.

Type	Default
component	AttachmentPreviewList

AutocompleteSuggestionHeader

Custom UI component to override the default suggestion header component.

Type	Default
component	Header

AutocompleteSuggestionItem

Custom UI component to override the default suggestion Item component.

Type	Default
component	Item

AutocompleteSuggestionList

Custom UI component to override the default List component that displays suggestions.

Type	Default
component	List

Avatar

Custom UI component to display a user's avatar.

Type	Default
component	Avatar

channelQueryOptions

Optional configuration parameters used for the initial channel query. Applied only if the value of channel.initialized is false. If the channel instance has already been initialized (channel has been queried), then the channel query will be skipped and channelQueryOptions will not be applied.

In the example below, we specify, that the first page of messages when a channel is queried should have 20 messages (the default is 100). Note that the channel prop has to be passed along channelQueryOptions.

import { ChannelQueryOptions } from 'stream-chat';
import { Channel, useChatContext } from 'stream-chat-react';

const channelQueryOptions: ChannelQueryOptions = {
  messages: { limit: 20 },
};

type ChannelRendererProps = {
  id: string;
  type: string;
};

const ChannelRenderer = ({ id, type }: ChannelRendererProps) => {
  const { client } = useChatContext();
  return (
    <Channel channel={client.channel(type, id)} channelQueryOptions={channelQueryOptions}>
      {/* Channel children */}
    </Channel>
  );
};

Type
ChannelQueryOptions

CooldownTimer

Custom UI component to display the slow mode cooldown timer.

Type	Default
component	CooldownTimer

DateSeparator

Custom UI component for date separators.

Type	Default
component	DateSeparator

doDeleteMessageRequest

Custom action handler to override the default client.deleteMessage(message.id) function.

Type
(message: StreamMessage<StreamChatGenerics>) => Promise<MessageResponse<StreamChatGenerics>>

The function can execute different logic for message replies compared to messages in the main message list based on the parent_id property of StreamMessage object:

import { Channel, StreamMessage } from 'stream-chat-react';
import type { MyStreamChatGenerics } from './types';

const doDeleteMessageRequest = async (message: StreamMessage<MyStreamChatGenerics>) => {
    if (message.parent_id) {
        // do something before / after deleting a message reply
    } else {
        // do something before / after deleting a message
    }
}

const App = () => (
  {/* more components */}
    <Channel doDeleteMessageRequest={ doDeleteMessageRequest }>
        {/* more components */}
    </Channel>
  {/* more components */}
);

doMarkReadRequest

Custom action handler to override the default channel.markRead request function (advanced usage only). The function takes two arguments:

Argument	Type	Description
channel	Channel	The current channel object instance
setChannelUnreadUiState	(state: ChannelUnreadUiState) => void	Function that allows us to set the unread state for the components reflecting the unread message state.

Type
function

doSendMessageRequest

Custom action handler to override the default channel.sendMessage request function (advanced usage only).

Type
function

doUpdateMessageRequest

Custom action handler to override the default client.updateMessage request function (advanced usage only).

Type
function

dragAndDropWindow

If true, chat users will be able to drag and drop file uploads to the entire channel window.

Type	Default
boolean	false

EditMessageInput

Custom UI component to override default edit message input.

Type	Default
component	EditMessageForm

emojiSearchIndex

Custom search mechanism instance or object to enable emoji autocomplete.

Type	Default
object	undefined

EmojiPicker

Custom UI component to be rendered in the MessageInput component, see Emoji Picker guide for more information.

Type	Default
component	undefined

EmptyPlaceholder

Custom UI component to be shown if no active channel is set, defaults to null and skips rendering the Channel component.

Type	Default
component	null

EmptyStateIndicator

Custom UI component to be displayed when the MessageList or VirtualizedMessageList is empty.

Type	Default
component	EmptyStateIndicator

enrichURLForPreview

A global flag to toggle the URL enrichment and link previews in MessageInput. The feature is disabled by default. It can be overridden on Thread and MessageList level through additionalMessageInputProps or directly on MessageInput level through urlEnrichmentConfig prop. See the guide Link Previews in Message Input for more.

Type	Default
boolean	false

enrichURLForPreviewConfig

Global configuration for link preview generation in all the MessageInput components. See the guide Link Previews in Message Input for more.

Type
Omit<URLEnrichmentConfig, 'enrichURLForPreview'>

FileUploadIcon

Custom UI component for file upload icon.

Type	Default
component	FileUploadIcon

GiphyPreviewMessage

Custom UI component to render a Giphy preview in the VirtualizedMessageList.

Type	Default
component	GiphyPreviewMessage

giphyVersion

The Giphy version to render - check the keys of the Image Object for possible values.

Type	Default
string	'fixed_height'

HeaderComponent

Custom UI component to render at the top of the MessageList.

Type	Default
component	none

imageAttachmentSizeHandler

A custom function to provide size configuration for image attachments

Type
(a: Attachment, e: HTMLElement) => ImageAttachmentConfiguration

initializeOnMount

Allows to prevent triggering the channel.watch() (triggers channel query HTTP request) call when mounting the Channel component (the default behavior) with uninitialized (channel.initialized) Channel instance. That means that no channel data from the back-end will be received neither channel WS events will be delivered to the client. Preventing to initialize the channel on mount allows us to postpone the channel creation in the Stream's DB to a later point in time, for example, when a first message is sent:

import { useCallback } from 'react';
import {
  getChannel,
  MessageInput as StreamMessageInput,
  MessageInputProps,
  MessageToSend,
  useChannelActionContext,
  useChatContext,
} from 'stream-chat-react';
import { Message, SendMessageOptions } from 'stream-chat';

import { useChannelInitContext } from '../../context/ChannelInitProvider';
import type { MyStreamChatGenerics } from '../../types';

export const MessageInput = (props: MessageInputProps) => {
  const { client } = useChatContext();
  const { sendMessage } = useChannelActionContext();
  const { setInitializedChannelOnMount } = useChannelInitContext();

  const submitHandler: MessageInputProps['overrideSubmitHandler'] = useCallback(
    async (
      message: MessageToSend<MyStreamChatGenerics>,
      channelCid: string,
      customMessageData?: Partial<Message<MyStreamChatGenerics>>,
      options?: SendMessageOptions,
    ) => {
      const [channelType, channelId] = channelCid.split(':');
      const channel = client.channel(channelType, channelId);
      if (!channel.initialized) {
        await getChannel({ channel, client });
        setInitializedChannelOnMount(true);
      }

      await sendMessage(message, customMessageData, options);
    },
    [client, sendMessage, setInitializedChannelOnMount],
  );

  return <StreamMessageInput {...props} overrideSubmitHandler={submitHandler} />;
};

Type	Default
boolean	true

markReadOnMount

Configuration parameter to mark the active channel as read when mounted (opened). By default, the channel is marked read on mount.

Type	Default
boolean	true

Input

Custom UI component handling how the message input is rendered.

Type	Default
component	MessageInputFlat

LinkPreviewList

Custom component to render link previews in MessageInput.

Type	Default
component	LinkPreviewList

LoadingErrorIndicator

Custom UI component to be shown if the channel query fails.

Type	Default
component	LoadingErrorIndicator

LoadingIndicator

Custom UI component to render while the MessageList is loading new messages.

Type	Default
component	LoadingIndicator

maxNumberOfFiles

The maximum number of attachments allowed per message, defaults to the Stream Chat API maximum.

Type	Default
number	10

Message

Custom UI component to display a message in the standard MessageList.

Type	Default
component	MessageSimple

MessageDeleted

Custom UI component for a deleted message.

Type	Default
component	MessageDeleted

MessageListNotifications

Custom UI component that displays message and connection status notifications in the MessageList.

Type	Default
component	DefaultMessageListNotifications

MessageNotification

Custom UI component to display a notification when scrolled up the list and new messages arrive.

Type	Default
component	MessageNotification

MessageOptions

Custom UI component for message options popup.

Type	Default
component	MessageOptions

MessageRepliesCountButton

Custom UI component to display message replies.

Type	Default
component	MessageRepliesCountButton

MessageStatus

Custom UI component to display message delivery status.

Type	Default
component	MessageStatus

MessageSystem

Custom UI component to display system messages.

Type	Default
component	EventComponent

MessageTimestamp

Custom UI component to display a timestamp on a message. This does not include a timestamp for edited messages.

Type	Default
component	MessageTimestamp

See also Timestamp.

MessageBouncePrompt

Custom UI component for the content of the modal dialog for messages that got bounced by the moderation rules.

Type	Default
component	MessageBouncePrompt

ModalGallery

Custom UI component for viewing message's image attachments.

Type	Default
component	ModalGallery

multipleUploads

Whether to allow multiple attachment uploads on a message.

Type	Default
boolean	true

onMentionsClick

Custom action handler function to run on click of an @mention in a message.

Type
function

onMentionsHover

Custom action handler function to run on hover of an @mention in a message.

Type
function

optionalMessageInputProps

If dragAndDropWindow prop is true, the props to pass to the MessageInput component (overrides props placed directly on MessageInput).

Type
object

PinIndicator

Custom UI component to override default pinned message indicator.

Type	Default
component	PinIndicator

QuotedMessage

Custom UI component to override quoted message UI on a sent message.

Type	Default
component	QuotedMessage

QuotedMessagePreview

Custom UI component to override the message input's quoted message preview.

Type	Default
component	QuotedMessagePreview

ReactionSelector

Custom UI component to display the reaction selector.

Type	Default
component	ReactionSelector

ReactionsList

Custom UI component to display the list of reactions on a message.

Type	Default
component	ReactionsList

SendButton

Custom UI component for send button.

Type	Default
component	SendButton

shouldGenerateVideoThumbnail

You can turn on/off thumbnail generation for video attachments

Type
boolean

skipMessageDataMemoization

If true, skips the message data string comparison used to memoize the current channel messages (helpful for channels with 1000s of messages).

Type	Default
boolean	false

ThreadHead

Custom UI component to be displayed at the beginning of a thread. By default, it is the thread parent message. It is composed of Message context provider component and ThreadStart component. The latter can be customized by passing custom component to Channel props. The ThreadHead component defaults to and accepts the same props as MessageSimple.

Type	Default
component	ThreadHead

ThreadHeader

Custom UI component to display the header of a Thread.

Type	Default
component	DefaultThreadHeader

ThreadInput

Custom UI component to replace the MessageInput of a Thread. For the applications using theme version 1, the default is MessageInputSmall. Applications using theme version 2 will use MessageInputFlat by default.

Type	Default
component	MessageInputSmall (theme v1) / MessageInputFlat (theme v2)

ThreadStart

Custom UI component to display the start of a threaded MessageList.

Type	Default
component	DefaultThreadStart

Timestamp

Custom UI component to display a date used in timestamps. It's used internally by the default MessageTimestamp, and to display a timestamp for edited messages.

Type	Default
component	Timestamp

TriggerProvider

Optional context provider that lets you override the default autocomplete triggers.

Type	Default
component	DefaultTriggerProvider

TypingIndicator

Custom UI component for the typing indicator.

Type	Default
component	TypingIndicator

UnreadMessagesNotification

Custom UI component that indicates a user is viewing unread messages. It disappears once the user scrolls to UnreadMessagesSeparator.

Type	Default
component	UnreadMessagesNotification

UnreadMessagesSeparator

Custom UI component inserted before the first message marked unread.

Type	Default
component	UnreadMessagesSeparator

videoAttachmentSizeHandler

A custom function to provide size configuration for video attachments

Type
(a: Attachment, e: HTMLElement) => VideoAttachmentConfiguration

VirtualMessage

Custom UI component to display a message in the VirtualizedMessageList.

Type	Default
component	MessageSimple