Entry points and native handlers

An app built with React Native CLI imports its components from stream-chat-react-native. An Expo app imports the same components from stream-chat-expo. Both packages re-export one core SDK, and each registers the native handlers of its toolchain, the functions and components that pick images, play audio or copy text with the packages you install. An app that shows AI responses also imports from the ai-components entry point of its package.

This page lists the entry points, what they export and which packages they need, and every native handler. Installation has the short version.

Install one of the two packages, never both. Metro doesn't drop unused code, so the AI components are a separate entry point, and the main entry point never imports from it. An app that never imports ai-components doesn't bundle them, or the packages they use.

stream-chat-react-native and stream-chat-expo

These are the core UI. Both packages export the same components, contexts and hooks, from the core package stream-chat-react-native-core, which they depend on. Import from your toolchain's package, not from stream-chat-react-native-core. Importing the core alone registers no native handlers. Each package also exports defaultNativeHandlers, the handlers it registers. See Overriding a handler.

The packages don't re-export stream-chat. Import the client and the state classes, such as StreamChat and ChannelPaginator, from stream-chat itself.

The main exports by area:

Reference, Hooks lists the hooks by state area, starting with State and entity hooks. Every component's props are in the Component reference, starting with Chat.

stream-chat-react-native/ai-components and stream-chat-expo/ai-components

The entry point exports the components for AI chat:

• StreamingMessageView renders Markdown as it streams in, with a typewriter effect, syntax highlighting, tables and charts.
• ComposerView is a composer with attachment previews, a bottom sheet of options, speech to text, and a send button that turns into a stop button while a response is generated. SpeechToTextButton is its dictation button.
• AITypingIndicatorView shows a state of the model, such as "Thinking", as shimmering text.
• Markdown, SyntaxHighlighter and VictoryChart are the renderers StreamingMessageView uses.
• useStreamingMessage drives the typewriter effect, useDictation the speech to text, and isDictationAvailable() tells whether dictation is part of the build.
• StreamTheme provides the theme of these components, which useTheme from this entry point reads. Wrap the AI components in it.

The entry point doesn't import the main entry point, so it doesn't register the main native handlers. It registers only the two native views its components use, NativeShimmerView and, on Android, PerfText, which renders highlighted code as one native text view. Importing both entry points registers them twice, which is harmless.

Several names exist in both entry points, as different exports. For example, AITypingIndicatorView, StreamingMessageView and useStreamingMessage from the main entry point belong to the chat UI. The theme exports of this entry point, Theme, useTheme, defaultTheme, mergeThemes and DeepPartial, belong to StreamTheme, not to the chat theme.

What the entry point needs:

• Charts. It imports @shopify/react-native-skia and victory-native, so an app that imports it installs both.
• Babel. Its zod dependency uses export * as syntax, which the React Native Babel preset doesn't transform. Add @babel/plugin-transform-export-namespace-from to babel.config.js, before react-native-worklets/plugin.
• Dictation. On iOS, the dictation module is compiled into the app only when you opt in, because App Store Connect asks every app whose binary references the Speech framework for a speech recognition usage description. With React Native CLI, set $StreamChatEnableDictation = true in the Podfile, before use_native_modules!, and add NSMicrophoneUsageDescription and NSSpeechRecognitionUsageDescription to Info.plist. On Android, add the RECORD_AUDIO permission to your app's AndroidManifest.xml. With Expo, add the stream-chat-expo config plugin to app.json, which does both. On iOS without the opt-in, SpeechToTextButton renders nothing and isDictationAvailable() returns false.
• Media and clipboard. The composer's media picker uses react-native-image-picker or expo-image-picker, and the copy button of code blocks uses @react-native-clipboard/clipboard or expo-clipboard, whichever is installed. These don't go through the native handlers.

See the AI integrations overview and SDK integration.

Native handlers

The core SDK doesn't import any native package itself. It calls native handlers, a function or a component for each platform capability, such as pickImage, setClipboardString or Video. stream-chat-react-native and stream-chat-expo each register an implementation of every handler when they're first imported, built on the packages of their toolchain.

Each implementation checks at import time whether its package is installed. When it isn't, the package registers null for most handlers, and the SDK leaves out the feature. For example, without takePhoto the composer has no camera button, without shareImage the image gallery has no share button, and without setClipboardString the message menu has no copy action. triggerHaptic is the exception. Without its package, it's a function that does nothing.

Handlers

Where a package is listed with a fallback, the handler uses the first package that is installed. A few handlers need more than one package to turn a feature on. The share button of the image gallery needs shareImage and a file system handler, saveFile or deleteFile. The media grid of the attachment picker needs getPhotos, getLocalAssetUri and both iOS 14 handlers.

Overriding a handler

registerNativeHandlers() takes an object with the handlers to replace, and keeps the others. Call it once, at the top level of a module, after the import of stream-chat-react-native or stream-chat-expo, so it runs after the package has registered its defaults. Calls inside a component run again on every render.

To change what a default handler does, wrap it. defaultNativeHandlers holds the handlers the package registered, with null for most of those whose package isn't installed. This override makes the camera button take photos only, never videos:

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

const defaultTakePhoto = defaultNativeHandlers.takePhoto;

if (defaultTakePhoto) {
  registerNativeHandlers({
    takePhoto: (options) =>
      defaultTakePhoto({ ...options, mediaType: "image" }),
  });
}

import {
  defaultNativeHandlers,
  registerNativeHandlers,
} from "stream-chat-expo";

const defaultTakePhoto = defaultNativeHandlers.takePhoto;

if (defaultTakePhoto) {
  registerNativeHandlers({
    takePhoto: (options) =>
      defaultTakePhoto({ ...options, mediaType: "image" }),
  });
}

Import the file once, for example from the file that renders OverlayProvider. The SDK reads a handler each time it uses it, so an override applies from then on. Register overrides before the first render, so every part of the UI uses them.

To replace a handler, register your own function with the same signature. For example, to turn off haptic feedback:

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

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

With React Native CLI, wrapping compressImage is also how you set the color painted behind transparent images. The SDK passes only the quality, the size and the URI, and the default handler paints white unless it gets backgroundColor, a color string or an RGBA integer:

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

const defaultCompressImage = defaultNativeHandlers.compressImage;

if (defaultCompressImage) {
  registerNativeHandlers({
    compressImage: (params) =>
      defaultCompressImage({ ...params, backgroundColor: "#000000" }),
  });
}

Pass backgroundColor: null to leave the background to the platform. stream-chat-expo has no such option.

overrideAudioRecordingConfiguration changes the recording settings of the registered Audio. It receives the current configuration and returns the new one, which the SDK sets on Audio when you register it. Without a registered Audio, it has no effect. The configuration types are RNCLIAudioRecordingConfiguration and ExpoAudioRecordingConfiguration.

Handler types

The parameter of registerNativeHandlers() types every handler. The SDK doesn't export a type for each one, so derive it:

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

type NativeHandlers = Parameters<typeof registerNativeHandlers>[0];
type TakePhoto = NonNullable<NativeHandlers["takePhoto"]>;

PickImageOptions, PlaybackStatus, RecordingStatus and SoundReturnType, the types of the handlers' data, are exported too.

Optional packages

The core SDK and each package declare their optional packages as optional peer dependencies. Install one only if you use the feature that needs it. The required peers are on Installation.

Both toolchains:

stream-chat-react-native:

stream-chat-expo needs Expo SDK 53 or later. Its packages take any version:

Most of these are native modules, so rebuild the app after adding one.

Best practices

• Import from stream-chat-react-native or stream-chat-expo, never from stream-chat-react-native-core, so the native handlers are registered.
• Import ai-components only if the app renders AI components. One import anywhere in the app bundles them, with the packages they need.
• Register handler overrides once, at the top level of a module, before the first render.
• Wrap the default handler from defaultNativeHandlers rather than rewriting it, and keep its signature.
• Install only the optional packages of the features you use, and add the permissions each one needs.