Channel
The Channel
component is a React Context provider that wraps all the logic, functionality, and UI for an individual chat channel.
It provides four separate contexts to its children:
ChannelStateContext
- stateful data (ex:messages
ormembers
)ChannelActionContext
- action handlers (ex:sendMessage
oropenThread
)ComponentContext
- custom component UI overrides (ex:Avatar
orMessage
)TypingContext
- object of currently typing users (i.e.,typing
)
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'],
});
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 |
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 |
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 |
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 |
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
. The component uses MessageInputFlat
by default.
Type | Default |
---|---|
component | MessageInputFlat |
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 |