React Introduction

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

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

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)

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)

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 is a UI component that allows smooth transitions between Channel and Thread components.

The ChannelHeader displays pertinent information regarding the currently active channel, including image and title.

For more information visit ChannelHeader.

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.

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.

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.

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;

• Changed the theme to messaging dark

• Filtered the ChannelList by type messaging and sorted by latest messages

• Added a custom paginator component to load more items when scrolling threshold is reached

• Used MessageTeam as the Message UI component on MessageList

• Used MessageInputFlat as the Input UI component on MessageInput

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.