This is documentation for the release candidate Stream Chat React Native SDK v6. For the latest stable version, see the latest version (v5).

Installation

Installation and usage of our Stream Chat React Native SDK is simple and involves the following steps:

Prerequisites

First things first, make sure you have set up the development environment for React Native. You can find the official guide here.

For Expo, you can follow this guide.

Add Stream’s Chat SDK and its peer dependencies

In order to install the Stream Chat React Native SDK, run the following command in your terminal of choice:

Terminal

yarn add stream-chat-react-native

Terminal

npx expo install stream-chat-expo

Stream Chat React Native SDK requires installing some peer dependencies to provide you with a great chat experience. You can run the following command to install them:

Terminal

yarn add @react-native-community/netinfo react-native-gesture-handler react-native-reanimated react-native-svg

Terminal

npx expo install @react-native-community/netinfo expo-image-manipulator react-native-gesture-handler react-native-reanimated react-native-svg

So what did we install precisely?

@react-native-community/netinfo for SDK to respond to network changes.
react-native-gesture-handler to handle gestures within the SDK.
react-native-reanimated to compress image uploads.
react-native-svg for SVG support.

@react-native-community/netinfo for SDK to respond to network changes.
react-native-gesture-handler to handle gestures within the SDK.
expo-image-manipulator to compress image uploads.
react-native-reanimated to compress image uploads.
react-native-svg for SVG support.

Opt-in features

There are a few features that can be optionally added within the SDK, which would need additional dependencies to be installed. These features are:

Video playing

Play video and audio attachments within messages in the chat.

Terminal

yarn add react-native-video

Terminal

npx expo install expo-av

Voice recording

Record and send voice messages and play them back within the chat.

Terminal

yarn add react-native-audio-recorder-player react-native-blob-util

Terminal

npx expo install expo-av

Configuring permissions

react-native-audio-recorder-player for microphone access for voice recording.

An example AndroidManifest.xml would look like this with permissions:

  <uses-permission android:name="android.permission.RECORD_AUDIO" />

An example Info.plist would look like this with permissions:

<key>NSMicrophoneUsageDescription</key>
<string>$(PRODUCT_NAME) would like to use your microphone for voice recording.</string>

expo-av for microphone access for voice recording.

An example app.json config for expo would look like this to add permissions to the Info.plist on iOS, using the config plugins:

{
  "expo": {
    "plugins": [
      [
        "expo-av",
        {
          "microphonePermission": "$(PRODUCT_NAME) would like to use your microphone for voice recording."
        }
      ]
    ]
  }
}

For Android on Expo, most of the most permissions are added automatically by libraries that you use in your app either with config plugins or with a package-level AndroidManifest.xml. Read more here.

Share attachments within the message to others.

Terminal

yarn add react-native-blob-util react-native-share

Terminal

npx expo install expo-sharing

Haptic feedback

Provide haptic feedback to the user.

Terminal

yarn add react-native-haptic-feedback

Terminal

npx expo install expo-haptics

Copy message

Copy the text message content to the clipboard.

Terminal

yarn add @react-native-clipboard/clipboard

Terminal

npx expo install expo-clipboard

Share files from the device within the chat.

Terminal

yarn add react-native-document-picker

Terminal

npx expo install expo-document-picker

Capture image and upload attachment

Capture images from the camera and upload them as attachments in the chat.

Terminal

yarn add react-native-image-picker

Terminal

npx expo install expo-image-picker

Configuring permissions

react-native-image-picker for camera access.

On Android, an example AndroidManifest.xml would look like this with permissions:

  <uses-permission android:name="android.permission.CAMERA" />

On iOS, An example Info.plist would look like this with permissions:

<key>NSCameraUsageDescription</key>
<string>$(PRODUCT_NAME) would like to use your camera to share image in a message.</string>

expo-image-picker for camera access.

An example app.json config for expo would look like this to add permissions to the Info.plist on iOS, using the config plugins:

{
  "expo": {
    "plugins": [
      [
        "expo-image-picker",
        {
          "cameraPermission": "$(PRODUCT_NAME) would like to use your camera to share image in a message."
        }
      ]
    ]
  }
}

Pick image using Native Image Picker

Pick gallery image using native image picker and upload them as attachments in the chat.

Terminal

yarn add react-native-image-picker

Terminal

npx expo install expo-image-picker

Configuring permissions

react-native-image-picker for camera access.

On android, there are no permissions required.

On iOS, An example Info.plist would look like this with permissions:

<key>NSPhotoLibraryUsageDescription</key>
<string>$(PRODUCT_NAME) would like access to your photo gallery to share image in a message.</string>
<key>NSPhotoLibraryAddUsageDescription</key>
<string>$(PRODUCT_NAME) would like to save photos to your photo gallery after downloading from a message.</string>

expo-image-picker for camera access.

An example app.json config for expo would look like this to add permissions to the Info.plist on iOS, using the config plugins:

{
  "expo": {
    "plugins": [
      [
        "expo-image-picker",
        {
          "photosPermission": "$(PRODUCT_NAME) would like to use your device gallery to attach image in a message."
        }
      ]
    ]
  }
}

Built-in image media library

Pick image using built-in media library and upload them as attachments in the chat.

Terminal

yarn add @react-native-camera-roll/camera-roll

Terminal

npx expo install expo-media-library

Configuring permissions

@react-native-camera-roll/camera-roll for gallery/photo library access.

An example AndroidManifest.xml would look like this with permissions:

  <uses-permission android:name="android.permission.READ_MEDIA_IMAGES" />
  <uses-permission android:name="android.permission.READ_MEDIA_VIDEO" />
  <uses-permission android:name="android.permission.READ_EXTERNAL_STORAGE"
    android:maxSdkVersion="32" />
  <uses-permission android:name="android.permission.WRITE_EXTERNAL_STORAGE" />

An example Info.plist would look like this with permissions:

<key>NSPhotoLibraryUsageDescription</key>
<string>$(PRODUCT_NAME) would like access to your photo gallery to share image in a message.</string>
<key>NSPhotoLibraryAddUsageDescription</key>
<string>$(PRODUCT_NAME) would like to save photos to your photo gallery after downloading from a message.</string>

expo-media-library for gallery/photo library access.

An example app.json config for expo would look like this to add permissions to the Info.plist on iOS, using the config plugins:

{
  "expo": {
    "plugins": [
      [
        "expo-media-library",
        {
          "photosPermission": "$(PRODUCT_NAME) would like access to your photo gallery to share image in a message.",
          "savePhotosPermission": "$(PRODUCT_NAME) would like to save photos to your photo gallery after downloading from a message."
        }
      ]
    ]
  }
}

Offline support

Enable offline support in the app.

Terminal

yarn add @op-engineering/op-sqlite

Terminal

npx expo install @op-engineering/op-sqlite

The overall installation of the optional dependencies would look like this:

@react-native-camera-roll/camera-roll for accessing device gallery.
react-native-video for Video and Audio playback support.
react-native-audio-recorder-player for Audio recording and async audio messages support.
react-native-blob-util to perform file operations like save, delete, while sharing or access the cache directory while audio recording.
react-native-share for Attachment sharing support.
react-native-haptic-feedback for user haptics feedback.
@react-native-clipboard/clipboard for Copy message support.
react-native-document-picker to access device media files.
react-native-image-picker to capture images to attach them in the message.
@op-engineering/op-sqlite to enable Offline support in the app.

expo-av for Video and Audio playback, recording and async audio messages support.
expo-file-system to perform file operations like save, delete, while sharing or access the cache directory while audio recording.
expo-media-library for accessing device gallery.
expo-sharing for Attachments sharing support.
expo-haptics for user haptics support.
expo-clipboard for Copy message support.
expo-document-picker to access device media files.
expo-image-picker to capture images to attach them in the message or use native image picker.
@op-engineering/op-sqlite to enable Offline support in the app.

Please follow along the linked documentation of each optional dependencies so as to support them correctly in your application.

Additional Steps

Some dependencies require us to make changes to our application for all functionalities to be available.

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:

module.exports = {
  presets: [
    ... // don't add it here :)
  ],
  plugins: [
    ...
    'react-native-reanimated/plugin',
  ],
};

react-native-reanimated/plugin has to be listed last.

After installation, wrap your entry point with <GestureHandlerRootView> or gestureHandlerRootHOC:

import { GestureHandlerRootView } from 'react-native-gesture-handler';

export default function App() {
  return <GestureHandlerRootView style={{ flex: 1 }}>{/* content */}</GestureHandlerRootView>;
}

The entry point of your app exists usually either in index.js or App.tsx file. In case of navigation with Expo Router v3.x, the entry point is inside app/_layout.js.

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

react-native - additional installation steps

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

Terminal

npx pod-install
yarn ios

Terminal

yarn android

Terminal

yarn run ios

Terminal

yarn run android

Overview