Native Handlers

Stream Chat React Native uses native features and supports both React Native CLI and Expo, each with different native packages.

To handle this, the SDK is split into stream-chat-react-native-core plus either stream-chat-react-native or stream-chat-expo. The non-core package calls registerNativeHandlers so the core package can use platform-specific implementations for the same tasks.

Best Practices

• Register handlers once during app startup, not inside components.
• Mirror the SDK’s handler signatures to avoid runtime mismatches.
• Override only the handlers you need to change; keep the rest default.
• Verify Expo vs. RN CLI dependencies before swapping implementations.
• Test media flows after overriding handlers to confirm parity.

Overriding Handlers

You can override native handlers with registerNativeHandlers. Use the same function the SDK uses internally, return the same types, and follow the SDK type definitions in the default implementations.

Example

Haptic feedback is used for certain presses and in the image viewer. If you don’t want it, replace the handler.

import { registerNativeHandlers } from "stream-chat-react-native";

registerNativeHandlers({
  triggerHaptic: () => null,
});

Handlers

These handlers map to different native packages depending on whether you use Expo or React Native CLI.

Audio

The handler used to play audio files and for voice recording.

overrideAudioRecordingConfiguration

A handler to override the audio recording config used by Audio. It’s a transformer: input Audio.audioRecordingConfiguration, return a modified config of the same type. The result is set on the Audio singleton.

Types are defined in the SDK: RN CLI and Expo.

RN CLI follows react-native-audio-recorder-player config; Expo follows expo-av (and expo-audio is compatible with that config).

compressImage

Async function that compresses an image and returns the local uri.

deleteFile

Deletes a file at a local uri.

getLocalAssetUri

Gets the local uri of an image or remote asset.

getPhotos

Returns photos from the camera roll using after (offset) and first (count).

pickDocument

Opens the document picker and returns selected documents.

pickImage

Opens the native image picker and returns selected images.

saveFile

Saves a file from a URL to local storage.

SDK

String identifying which package is used: stream-chat-react-native or stream-chat-expo.

setClipboardString

Copies text to the clipboard.

shareImage

Shares an image using the OS share sheet.

takePhoto

Opens the OS camera to capture an image or video and returns the result.

triggerHaptic

Triggers haptic feedback for a given type.

Sound

Renders audio attachments.

Video

Renders video in the image gallery when a video attachment is opened.