React Introduction
Confused about "React Introduction"?
Let us know how we can improve our documentation:
Connect to Stream Chat
Copied!Confused about "Connect to Stream Chat"?
Let us know how we can improve our documentation:
Once you have signed up for Stream Chat, to begin using our React component library, you need to instantiate a chat client and connect as a user. User tokens must be generated server-side, and once you have an ID and token, you can connect to chat.
1
2
3
4
5
import { StreamChat } from 'stream-chat';
const chatClient = StreamChat.getInstance(apiKey);
chatClient.connectUser({ id: userId }, userToken);
React Component Overview
Copied!Confused about "React Component Overview"?
Let us know how we can improve our documentation:
Our React Chat component library includes everything you need to build a fully functioning chat experience, with support for rich messages, reactions, threads, image uploads, videos, and more. This library was designed to enable customers to get an application up and running quickly and efficiently while supporting the customizability to support even the most complex use cases.
Below is a sample of basic chat components in the React library:
1
2
3
4
5
6
7
8
9
10
11
12
13
const App = () => (
<Chat client={chatClient}>
<ChannelList />
<Channel>
<Window>
<ChannelHeader />
<MessageList />
<MessageInput />
</Window>
<Thread />
</Channel>
</Chat>
);
Chat
Copied!Confused about "Chat"?
Let us know how we can improve our documentation:
The Chat component is a React context provider that wraps the entire application. Its children consume the ChatContext
, which includes the instance of the Stream Chat client. Here you can find more information about the Chat component.
To access the ChatContext
within child components, use const chatContext = useContext(ChatContext)
Channel
Copied!Confused about "Channel"?
Let us know how we can improve our documentation:
The Channel component is another React context provider that passes relevant channel data to its children. Optional props for this component can be found on our docs page Channel.
To access the ChannelContext
within child components, use const channelContext = useContext(ChannelContext)
ChannelList
Copied!Confused about "ChannelList"?
Let us know how we can improve our documentation:
The ChannelList renders a list of channels and provides a preview of each. It accepts optional props such as filters
, options
, and sort
, which adjust the response of the channel query.
For a full list of props visit ChannelList.
Window
Copied!Confused about "Window"?
Let us know how we can improve our documentation:
Window is a UI component that allows smooth transitions between Channel and Thread components.
ChannelHeader
Copied!Confused about "ChannelHeader"?
Let us know how we can improve our documentation:
The ChannelHeader displays pertinent information regarding the currently active channel, including image and title.
For more information visit ChannelHeader.
MessageList
Copied!Confused about "MessageList"?
Let us know how we can improve our documentation:
The MessageList renders a list of messages and is a consumer of the ChannelContext
. It accepts optional props that override default action handlers and UI components. For example, if a custom message UI component is not supplied, MessageSimple
is rendered by default.
For a full list of props visit MessageList.
MessageInput
Copied!Confused about "MessageInput"?
Let us know how we can improve our documentation:
The MessageInput component is an HTML input with additional, built-in functionality. For example, it supports drag and drop image upload and includes an emoji picker. Similar to MessageList, it accepts optional props that override the Stream defaults.
For a full list of props visit MessageInput.
Thread
Copied!Confused about "Thread"?
Let us know how we can improve our documentation:
The Thread component enables your application to support threaded replies on a parent message. Within this component, you can customize its message list and text input. Full documentation is available here Thread.
Building Your App
Copied!Confused about "Building Your App"?
Let us know how we can improve our documentation:
Now that we've described the basic components of our React library, we can build a sample application.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
import React from 'react';
import { StreamChat } from 'stream-chat';
import {
Chat,
Channel,
ChannelHeader,
ChannelList,
InfiniteScrollPaginator,
MessageInput,
MessageInputFlat,
MessageList,
MessageTeam,
Thread,
Window,
} from 'stream-chat-react';
import 'stream-chat-react/dist/css/index.css';
const apiKey = process.env.REACT_APP_STREAM_KEY;
const userId = process.env.REACT_APP_USER_ID;
const userToken = process.env.REACT_APP_USER_TOKEN;
const filters = { type: 'messaging' };
const sort = { last_message_at: -1 };
const theme = 'messaging dark';
const Paginator = (props) => <InfiniteScrollPaginator threshold={300} {...props} />;
const chatClient = StreamChat.getInstance(apiKey);
chatClient.connectUser({ id: userId }, userToken);
const App = () => (
<Chat client={chatClient} theme={theme}>
<ChannelList filters={filters} sort={sort} Paginator={Paginator} />
<Channel>
<Window>
<ChannelHeader />
<MessageList Message={MessageTeam} />
<MessageInput Input={MessageInputFlat} />
</Window>
<Thread />
</Channel>
</Chat>
);
export default App;
In the above application, we added the following customizations:
Copied!Confused about "In the above application, we added the following customizations:"?
Let us know how we can improve our documentation:
Changed the theme to messaging dark
Filtered the
ChannelList
by typemessaging
and sorted by latest messagesAdded a custom paginator component to load more items when scrolling threshold is reached
Used
MessageTeam
as theMessage
UI component onMessageList
Used
MessageInputFlat
as theInput
UI component onMessageInput
Custom UI Components
Copied!Confused about "Custom UI Components"?
Let us know how we can improve our documentation:
Out of the box, the React component library comes with pre-built, default UI components and functionality that allow you to quickly get a chat application up and running. In addition, you have the ability to create your own custom UI components, action handlers, and events. This allows you to leverage the existing functionality of the component library while incorporating custom UI to meet your design specifications. In the below example, we outline how to create a custom message UI component and inject it into the MessageList
component.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
import React, { useContext } from 'react';
import { Avatar, ChatContext, usePinHandler } from 'stream-chat-react';
export const CustomMessage = (props) => {
const { addNotification, getPinMessageErrorNotification, message, pinPermissions } = props;
const { client } = useContext(ChatContext);
const { handlePin } = usePinHandler(message, pinPermissions, {
notify: addNotification,
getErrorNotification: getPinMessageErrorNotification,
});
const { image } = client.user;
return (
<div className={message.pinned ? 'pinned' : ''} onClick={handlePin}>
<Avatar image={image} />
<p>{message.text}</p>
</div>
);
};
Our simple, custom message component will display the user's image, the message text, and conditionally add a CSS class to pinned messages. We're importing the usePinHandler
hook to gain access to the handlePin
function, which toggles the pinned status of a message. Simply pass the custom component into the Message
prop of the MessageList
and all messages rendered in the list will use this UI component for their display.
1
2
3
4
5
6
7
8
9
10
11
12
13
const App = () => (
<Chat client={chatClient}>
<ChannelList />
<Channel>
<Window>
<ChannelHeader />
<MessageList Message={CustomMessage} />
<MessageInput />
</Window>
<Thread />
</Channel>
</Chat>
);
This process of creating a custom UI component and passing it as a prop into one of the high-level React components is a common pattern in the library and the standard way to style and customize a chat application. The same process pertains to overriding action handlers, where the components are pre-built with default functionality, but those functions can be overridden via props.
Check out our Readme for a full listing and description of the accessible props for each component.