Chat

Chat provides ChatContext, TranslationContext, and ThemeContext to child components. It sits below OverlayProvider.

Chat also tracks the WebSocket connection. See isOnline in ChatContext.

Best Practices

• Keep a single Chat provider per app unless you have a strong reason to isolate contexts.
• Use useCreateChatClient or a centralized client factory to avoid duplicate connections.
• Disconnect the client on logout to prevent stale sessions.
• Set closeConnectionOnBackground to match your push strategy (push requires no active socket).
• Pass theming and i18n consistently so children read from the same context.

General Usage

Render Chat inside OverlayProvider at a high level in your app.

import { StreamChat } from "stream-chat";
import {
  ChannelList,
  Chat,
  OverlayProvider,
  useCreateChatClient,
} from "stream-chat-react-native";

const chatApiKey = "REPLACE_WITH_API_KEY";
const chatUserId = "REPLACE_WITH_USER_ID";
const chatUserName = "REPLACE_WITH_USER_NAME";
const chatUserToken = "REPLACE_WITH_USER_TOKEN";

const user = {
  id: chatUserId,
  name: chatUserName,
};

export const App = () => {
  const chatClient = useCreateChatClient({
    apiKey: chatApiKey,
    userData: user,
    tokenOrProvider: chatUserToken,
  });

  if (!chatClient) {
    return null;
  }

  return (
    <OverlayProvider>
      <Chat client={chatClient}>
        <ChannelList />
      </Chat>
    </OverlayProvider>
  );
};

Context Providers

Chat provides ChatContext, ThemeContext, and TranslationContext via their hooks.

Props

client

Stream Chat client instance.

closeConnectionOnBackground

When false, the WebSocket stays connected in the background. For push notifications, the user must not have an active WebSocket connection. By default, the socket disconnects in background and reconnects on foreground.

enableOfflineSupport

Enables offline support for the chat. When enabled, messages and channels are cached locally and the app can work without an internet connection. Requires @op-engineering/op-sqlite to be installed.

See the offline support documentation for more details on setting this up.

getOfflineDbEncryptionKey

Encrypts the offline database at rest with SQLCipher, using the key this resolves to. Only relevant when enableOfflineSupport is enabled. Leaving it unset keeps the offline database unencrypted, which is the default.

Requires a native build of @op-engineering/op-sqlite that includes SQLCipher; without that build flag the key is accepted and then silently ignored, so the SDK refuses to open the database instead.

Chat throws a SqliteClientError from render when the database cannot be opened with the encryption you asked for, so wrap it in an error boundary. See encrypting the offline database for the failure codes and the recommended recovery for each.

i18nInstance

Streami18n instance for internationalization. See translations docs.

style

A theme object to customize styles. See theming docs.

UI Component Props

ImageComponent

Drop-in replacement for all underlying Image components in the SDK. Useful for offline image caching. See the Offline Support Guide.

LoadingIndicator

Custom loading indicator for the chat loading state (for example, before the DB is initialized).

isMessageAIGenerated

A callback that determines whether a message was AI generated. The default returns false.