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

npx expo install stream-chat-expo

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.

@react-native-community/netinfo for network state.
react-native-gesture-handler for gestures.
expo-image-manipulator to compress images.
react-native-reanimated for animations.
react-native-svg for SVG support.

Opt-in features

Optional features require additional dependencies.

Video playing

yarn add react-native-video

npx expo install expo-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

npx expo install expo-audio

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

npx expo install expo-sharing

Haptic feedback

Provide haptic feedback to the user.

yarn add react-native-haptic-feedback

npx expo install expo-haptics

Copy message

Copy the text message content to the clipboard.

yarn add @react-native-clipboard/clipboard

npx expo install expo-clipboard

Share files from the device.

yarn add @react-native-documents/picker

npx expo install expo-document-picker

Capture image and upload attachment

Capture images from the camera and upload them.

yarn add react-native-image-picker

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

yarn add react-native-image-picker

npx expo install expo-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

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

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

npx expo install @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

npx expo install @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.

expo-av for audio playback/recording.
expo-video for video playback/preview.
expo-file-system for file operations and cache access.
expo-media-library for gallery access.
expo-sharing for sharing.
expo-haptics for haptics.
expo-clipboard for clipboard.
expo-document-picker for file picking.
expo-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',
  ],
};