React Native Chat App Tutorial

To get started with this tutorial, make sure you have set up your development environment for React Native. The Stream Chat React Native SDK supports apps created with the React Native CLI as well as apps created with Expo.

To get started, create an application with either the React Native CLI, or the Expo CLI and install the necessary dependencies:

When prompted, select one of the blank templates.

Stream Chat has a number of peer dependencies that are required to take advantage of all of the out of the box features. It is suggested you follow the install instructions for each package to ensure it is properly setup. Most if not all of the required packages now support auto-linking so setup should be minimal.

Some dependencies require us to make changes to our application for all functionalities to be available. Please follow the steps highlighted in our Getting Started guide.

The most important steps to get started are:

• Add the Babel plugin for react-native-reanimated to your babel.config.js file in your application folder:

• Import react-native-gesture-handler at the top of your index.js file. It should look as follows:

Please also follow the steps mentioned in the links below for corresponding dependencies:

• react-native - additional installation steps
• react-native-image-crop-picker - additional installation steps
• react-native-cameraroll - additional installation steps

Now you should be able to run the app on simulator by running following command:

The Stream Chat SDK does not handle navigation, but libraries like React Navigation makes it easy for us to set up a stack navigator, and the three screens we need for our application.

Please install the following packages to get started with React Navigation, as mentioned in their documentation

We'll set up a simple Navigation stack to hold the necessary screens for navigation in our app, and start with a basic HomeScreen, which we will replace later with Chat related screens.

You can simply copy-paste following code in App.js file.

As mentioned in RNGH documentation, we also need to configure GestureHandlerRootView component. Although react-navigation library already use GestureHandlerRootView as a wrapper to enable gesture interactions. So for this tutorial, you don't need this step. But if you are using a native navigation library like wix/react-native-navigation you need to make sure that every screen is wrapped with GestureHandlerRootView.

If you have created a new app via GetStream dashboard, you will need to create few test channels and test users to see chat in action. You can easily do so from Chat Explorer. We would recommend you to create at least two three channels and three test users for nice tutorial experience.

If you prefer to create channels and users programatically, please check the documentation around Creating Channels and Creating Users.

The first thing we need to set up is the chat client, which is the low level JavaScript client used by the SDK to communicate with the Stream Chat service. The chat client is a JavaScript class object that we for the sake of simplicity in this tutorial will keep as a globally accessible variable. getInstance is a static method that takes apiKey as parameter and returns a singleton instance of the chat client.

You can safely use getInstance method to get the chat client instance, anywhere in your application. This way you can avoid passing the chat client instance around through context or props.

You can find apiKey on an GetStream dashboard for your app.

Let's create a separate file chatConfig.js to store all the config values. Generally you will want to store them in environment variables.

To keep things clean, let's create a separate react hook useChatClient.js. This hook will be responsible for connecting the user to chat and returning a boolean flag to indicate whether the client is connected.

Now we can add the logic for connecting the user. We'll use the connectUser method of the chat client to connect the user. When we say "connect", we are basically establishing a WebSocket connection with Stream backend so that user will start receiving WebSocket events for messages, reactions etc. It should only be used once per session per user. Opening multiple WebSockets per user opens your application to a myriad of problems, including performance, billing, and unexpected behavior. Please take a look at Best Practices guide for more details.

connectUser function required two parameters:

• User object: Must have an id field. User Ids can only contain characters a-z, 0-9, and special characters @, _ and -. It can have as many custom fields as you want, as long as the total size of the object is less than 5KB
• User Token: The user authentication token. See Tokens & Authentication for details

In real applications, you will want to store user id in local storage and fetch the token from your backend.

But for the sake of tutorial, we will just add the userId and user token to chatConfig.js file.

And now we can use these configs to connect the user to chat as follows:

Now useChatClient hook is ready to be integrated with our navigation stack. We will use the clientIsReady flag to determine whether to render the chat components or not.

A context should ideally be created to store the details of the current Channel and the Thread as set by the user on selecting the Channel from the ChannelList or Thread from the Message list. We will create the context AppContext such as:

To use the context we wrap the default component of the App.js file with AppProvider as follows:

The OverlayProvider is the highest level of the Stream Chat components and must be used near the root of your application (outside of any navigation stack). The OverlayProvider allows users to interact with messages on long press above the underlying views, use the full screen image viewer, and use the AttachmentPicker as a keyboard-esk view. The OverlayProvider can be used with no props provided but there are a plethora of props for customizing the components in the overlay.

Chat component mainly acts as provider of chatClient to the rest of the underlying components. It also takes care of the network connectivity, AppState handling etc.

You can choose to wrap your entire application in Chat similar to what is required for the OverlayProvider, or you can implement Chat at the screen level. Chat has one required prop - client, which is the instance of StreamChat you created. Also as mentioned earier in the tutorial, we can safely access the chatClient instance using getInstance method, since its a singleton.

Stream Chat for React Native provides a ChannelList component out of the box for displaying a list of channels.

Before we configure this component, let's first set up a screen for the channel list within the existing navigation stack. We will simply rename HomeScreen to ChannelListScreen.

Now we can render ChannelList component within ChannelListScreen.

ChannelList can be used with no props and will return all of the channels the set user has access to. Although in practical applications, you will probably want to only show the channels that current user is member of. For such filtering purpose, you can provide a filters prop to ChannelList which will filter the channels.

Additionally ChannelList component also takes sort prop for sorting the channels, and options props to provide additional query options. Please check the documentation for Querying Channels. For more information and various use cases of filters, sort and options.

You can add the press handler for the list item within the ChannelList component using a prop - onSelect. And this is where you can add the logic for navigating to the channel screen, where we will render the channel header, message list, input box etc. Let's implement the basic ChannelScreen component and logic for navigating from ChannelList to Channel Screen.

The channel screen will comprise three main components:

• MessageList component used to render the list of messages sent in a channel.
• MessageInput component used to render the input box needed to send messages, images, files, and commands to a channel.
• Channel component that holds all data related to a channel. It also acts as a bridge between MessageList and MessageInput component.

The Channel component takes the channel as a prop. The MessageList and MessageInput components don't need any props to be set, and we'll use the defaults set for these components.

At this point, you should be able to make use of various chat features like sending messages, uploading files, sending images, sending commands etc. as shown below.

Threads are a feature that allows you to start a conversation on a particular message in a message list, similar to what Slack offers.

Let's first setup a separate screen for thread within our navigation stack.

As explained in the previous section, when a user long presses on a message, it opens an overlay where the user can add a reaction and also can see a bunch of actions for the message. MessageList component accepts a prop function onThreadSelect which gets called when a user selects "Thread Reply" action on the message overlay.

You can now long press on a message and select "Thread Reply" action to open thread screen, which we will configure in the next step.

React Native Chat SDK provides a Thread component to easily configure thread screen for a message. This component needs to be wrapped inside Channel component with a boolean prop threadList set to true. This way, the Channel component is aware that it is being rendered within a thread screen and can avoid concurrency issues.

Chat RN SDK offers offline support OOTB. Offline support improves the load time of app and helps improve the user experience in case of slow network. Please read more about offline support in our documentation.

Install Sqlite Library

Add enableOfflineSupport prop

Add enableOfflineSupport prop on Chat component

If you run the app, you should be able to load the chat without any network.

Until now we have concluded the basic setup of chat within the application.

Although every application has a different UI and UX requirements, and the default designs are not always suitable for your application. Stream's React Native Chat is designed to be flexible and easily customizable.

Every underlying component within the chat SDK can be customized by passing a custom component as a prop to one of the core components, such as ChannelList, Channel or OverlayProvider depending on who the parent of that UI component is. This way, you can either fully customize the necessary UI component or wrap the default component with a custom view.

You will have access to necessary data within your custom component via props and context. To access information from these contexts we suggest using the hooks that are provided by the library. Following table lists some of the contexts provided by library and corresponding hooks for accessing them. You can find list of all the contexts and hooks on Contexts documentation.

We will cover the usage of context in the next section where we customize the message list.

Additionally you can also style the default component by simply providing a theme object containing custom styles.

We have demonstrated the power of Stream Chat React Native SDK by building open source clones of some popular chat applications such as Whatsapp, Slack and iMessage. Source code for all these projects is available under react-native-samples repository.

In the following sections, we will walk through some examples that will cover the basics around customizations and theming.

ChannelList is a FlatList of channels. To customize the channel list item, you can pass a prop Preview to ChannelList component. Default value of the Preview prop is ChannelPreviewMessenger component, basically the default UI component.

Objective: Add a light blue background for unread channels.

Let's start by creating a custom component for the list item, which simply returns the default UI component ChannelPreviewMessenger.

Unread count on channel can be accessed via unread prop. We will use this count to conditionally add a light blue background for unread channels.

You won't see any background color change for unread channels yet, since ChannelPreviewMessenger has a white background by default. Thus, we will need to first override the default background color to transparent to make the wrapped view background visible. To achieve this, we will use the theming system provided by the stream-chat-react-native library. You can find all the themeable properties in theme.ts file.

Similarly, along with of customizing the entire list item component, you can also customize the individual components within the list item. E.g., PreviewStatus, PreviewAvatar, PreviewMessage etc. You can use the visual guide to find out which components you can customize.

Every component within MessageList and MessageInput can be customized by passing a custom component as a prop to Channel component.

Objective: Replace default message UI with custom component

The most common use case of customizing the MessageList is to have a custom UI for the message. You can do so by providing a prop MessageSimple to Channel component as shown below.

Now that we have configured the component, let's render the text of the message on the UI. You can access the message object from the MessageContext context. MessageContext also gives you access to a boolean isMyMessage which we can use to style the message UI conditionally.

This is a really simplified version of custom message UI which only displays text. You can obviously add required functionality such as onPress, onLongPress handlers etc according to your needs. But generally, you wouldn't need to customize the entire message UI, but only the required parts such as MessageStatus, MessageAvatar etc. For this purpose, you can check the visual guide to decide which prop to pass to the Channel component. You can access MessageContext at every message level component.

Also, we would recommend you to check the following guides for a bit more advanced customizations:

• Message Customization guide
• Custom Attachments
• Custom Message Actions
• Custom Message Input Box
• MessageList For Livestream Application

That concludes the customization section for React Native Chat SDK. Now you should have a good overview of how to do a basic setup around chat components, and customize them as per your design/UX requirements. We have covered only the basic things, but the possibilities are endless.