This is documentation for Stream Chat React Native SDK v8, which is no longer actively maintained. For up-to-date documentation, see the latest version (v9).

Installation

Install the SDK in a few steps:

Best Practices

Choose RN CLI vs Expo tabs based on your app runtime; don't mix dependencies across runtimes.
Install only the optional features you need to keep bundle size and native setup lean.
Add required platform permissions as you enable features (audio, camera, media library).
Follow each dependency’s post-install steps to avoid runtime errors.
Keep Reanimated/Worklets Babel plugin last and wrap the app in GestureHandlerRootView.

Prerequisites

Set up the React Native development environment: React Native guide.

For Expo, follow this guide.

Add Stream Chat SDK and peer dependencies

Install the SDK:

yarn add stream-chat-react-native

Install peer dependencies:

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

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

Installed packages:

@react-native-community/netinfo for network state.
react-native-gesture-handler for gestures.
react-native-reanimated for animations.
react-native-worklets required by react-native-reanimated.
react-native-svg for SVG support.

Opt-in features

Optional features require additional dependencies.

Video playing

yarn add react-native-video

Voice recording and audio attachments

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

For Expo, both expo-av and expo-audio are supported.

npx expo install expo-av

expo-audio is supported from version 7.2.0 of stream-chat-expo.

Even though both libraries are supported and adapted to a singular API, different supported Expo versions do not work interoperably with each of the libraries.

More specifically, if you're using Expo 51.x.x or 52.x.x please make sure to keep using expo-av as expo-audio is unstable and will likely not work properly in those versions.

Conversely, if you're using Expo >=53.0.0, please make sure to use expo-audio as support for expo-av has stopped completely in favor of the new library. While it is already not supported, Expo 54 is not going to contain expo-av at all in Expo Go, meaning the sooner you get to go to Expo 53 and use the new library, the better.

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>

Setup varies slightly for each option:

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-audio 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": [
      // ... rest of the plugins
      [
        "expo-audio",
        {
          "microphonePermission": "$(PRODUCT_NAME) would like to use your microphone for voice recording."
        }
      ]
    ]
  }
}

On Android (Expo), most permissions are added automatically by libraries via config plugins or package-level AndroidManifest.xml. Read more here.

expo-video for video related configuration.

An example app.json config for expo would look like this:

{
  "expo": {
    "plugins": [
      // ... rest of the plugins
      [
        "expo-video",
        {
          "supportsBackgroundPlayback": true,
          "supportsPictureInPicture": true
        }
      ]
    ]
  }
}

Share attachments outside the app.

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

Haptic feedback

Provide haptic feedback to the user.

yarn add react-native-haptic-feedback

Copy message

Copy the text message content to the clipboard.

yarn add @react-native-clipboard/clipboard

Share files from the device.

yarn add @react-native-documents/picker

Capture image and upload attachment

Capture images from the camera and upload them.

yarn add react-native-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 images using the native picker and upload them.

yarn add react-native-image-picker

Configuring permissions

react-native-image-picker for photo library access.

On Android, no permissions are 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 images using the built-in media library and upload them.

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

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."
        }
      ]
    ]
  }
}

On Android (Expo), most permissions are added automatically by libraries via config plugins or package-level AndroidManifest.xml. Read more here.

Offline support

Enable offline support.

yarn add @op-engineering/op-sqlite

High-performance message list

For better performance with large message lists, you can use @shopify/flash-list instead of the default FlatList. This is especially useful for channels with thousands of messages.

yarn add @shopify/flash-list

See the FlashList documentation for more information on using FlashList with the SDK.

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

@react-native-camera-roll/camera-roll for gallery access.
react-native-video for video/audio playback.
react-native-audio-recorder-player for audio recording.
react-native-blob-util for file operations and cache access.
react-native-share for sharing.
react-native-haptic-feedback for haptics.
@react-native-clipboard/clipboard for clipboard.
@react-native-documents/picker for file picking (required over react-native-document-picker on React Native >=0.78.0).
react-native-image-picker for camera/gallery picking.
@op-engineering/op-sqlite for offline storage.

Follow each dependency's setup instructions to ensure proper integration.

Additional Steps

Some dependencies require extra app configuration:

Add the Babel plugin for react-native-reanimated in babel.config.js:

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

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

If you are using react-native-reanimated version >=4.0.0, you can replace the react-native-reanimated/plugin with react-native-worklets/plugin in your application's babel.config.js.

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