Installation

Install the SDK package for your toolchain, its peer dependencies, and stream-chat, the JavaScript client that holds the state. stream-chat-react-native and stream-chat-expo 10 and stream-chat 10 are release candidates, published under the rc tag. The SDK needs stream-chat 10.0.0-rc.26 or later.

The SDK needs React Native 0.79 or later with the New Architecture, and for Expo apps, Expo SDK 53 or later. stream-chat 10 needs Node 22.18 or later to install.

Install the SDK

yarn add stream-chat-react-native@rc stream-chat@rc

npx expo install stream-chat-expo@rc stream-chat@rc

The SDK depends on stream-chat itself. Your app imports from it too, for example ChannelPaginator and the types, so add it to your app at the version the SDK uses. Exactly one copy must resolve: a second copy makes the client and the objects your app creates come from different classes.

Then install the peer dependencies:

yarn add @react-native-community/netinfo react-native-gesture-handler react-native-reanimated react-native-worklets react-native-teleport react-native-svg react-native-safe-area-context

npx expo install @react-native-community/netinfo expo-image-manipulator react-native-gesture-handler react-native-reanimated react-native-worklets react-native-svg react-native-teleport react-native-safe-area-context

Configure the app

Add the Babel plugin of react-native-reanimated to babel.config.js, as the last plugin. With react-native-reanimated 4, the plugin is react-native-worklets/plugin:

module.exports = {
  presets: [
    // your presets
  ],
  plugins: [
    // your other plugins
    "react-native-worklets/plugin",
  ],
};

With react-native-reanimated 3, use react-native-reanimated/plugin instead. See the Reanimated installation guide.

Wrap the root of your app in GestureHandlerRootView:

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

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

For Expo Router, the root is app/_layout.tsx.

To build a first app, continue with the Quick start.

Best practices

• Install stream-chat next to the SDK and upgrade them together. The SDK depends on newer client features, so mismatched versions can fail at runtime even if installation succeeds.
• Use the package that matches your toolchain, and never install both.
• Install only the optional features you need. Each one adds a native module.
• Add the platform permissions a feature needs (microphone, camera, photo library) when you add it.
• Keep a single copy of dayjs (the SDK uses ^1.11.23). If your app declares dayjs too, use a compatible range.

Optional features

Each feature below turns on when its package is installed. Without the package, the SDK leaves the feature out.

Video playback

yarn add react-native-video

npx expo install expo-video

Voice recording and audio playback

yarn add react-native-nitro-sound react-native-nitro-modules react-native-blob-util

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

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

npx expo install expo-audio

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

Voice recording is off until you turn it on with the audioRecordingEnabled prop of Channel and Thread.

Sharing attachments

Share an attachment to another app.

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

npx expo install expo-sharing expo-file-system

Haptic feedback

yarn add react-native-haptic-feedback

npx expo install expo-haptics

Copying messages

Copy a message's text to the clipboard from the message menu.

yarn add @react-native-clipboard/clipboard

npx expo install expo-clipboard

Picking files

Attach files from the device.

yarn add @react-native-documents/picker

npx expo install expo-document-picker

Taking photos and using the system image picker

Take a photo with the camera, or pick images with the system picker.

yarn add react-native-image-picker

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

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

npx expo install expo-image-picker

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

Built-in media library

Pick photos and videos from the attachment picker's own grid instead of the system picker.

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

<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" />

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

npx expo install expo-media-library

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

Offline support

Keep channels and messages in a local SQLite database, so the app shows them before it connects and queues what the user does while offline.

yarn add @op-engineering/op-sqlite

npx expo install @op-engineering/op-sqlite

Then set enableOfflineSupport on Chat. See Offline support.

FlashList message list

MessageFlashList renders the message list with @shopify/flash-list 2.1 or later, in place of MessageList, which uses FlatList.

yarn add @shopify/flash-list

npx expo install @shopify/flash-list

Entry points

Each package has two entry points:

Metro doesn't drop unused code, so the AI components are kept out of the main entry point: an app that never imports ai-components doesn't bundle them. It imports @shopify/react-native-skia and victory-native for its charts, so an app that imports ai-components installs both, and its dictation is compiled into the iOS app only when you turn it on. See AI integrations.