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.

Info:

Use a single Chat provider per app unless you have a strong reason not to.

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>
  );
};
Tip:

You can use useCreateChatClient from stream-chat-react-native/stream-chat-expo to create a client and handle connect/disconnect.

Context Providers

Chat provides the following contexts, accessible via their hooks:

Props

Prop Description Type
client Stream Chat client instance. StreamChat
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. Defaults to true. boolean
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. Defaults to false. boolean
maxSyncEventsLimit Maximum number of /sync events replayed into the offline DB on reconnect. Above this, the SDK skips replay and refreshes actively watched channels via queryChannels/watch instead (last-sync timestamp still advances). Only used with enableOfflineSupport. Pass false to disable the limit. Defaults to 250. number | false
getOfflineDbEncryptionKey Encrypts the offline database at rest with SQLCipher, using the key this resolves to. Only relevant when enableOfflineSupport is enabled. Requires a native build of @op-engineering/op-sqlite that includes SQLCipher; without that build flag the key is accepted and then ignored. 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. Leaving it unset keeps the offline database unencrypted, which is the default. () => Promise<string | undefined>
useNativeMultipartUpload When true, Chat installs the SDK native multipart upload adapter on the client if the native handler is available. Multipart file uploads use the native module, while non-multipart requests continue through the existing axios adapter. Defaults to false. boolean
i18nInstance Streami18n instance for internationalization. See translations docs. Streami18n
style A theme object to customize styles. See theming docs. Themes are inherited from parent providers. A theme provided to OverlayProvider is the base theme that style merges into. Themes are not hoisted; a theme on Chat won't affect overlay components like the attachment picker. object
isMessageAIGenerated A callback that determines whether a message was AI generated. Defaults to () => false. (message: LocalMessage) => boolean

Native multipart uploads

stream-chat-react-native and stream-chat-expo register a native multipart upload handler during package initialization. To use it for the client managed by Chat, opt in with useNativeMultipartUpload.

<Chat client={chatClient} useNativeMultipartUpload>
  {/** App components */}
</Chat>

When enabled, the SDK wraps client.axiosInstance once. Multipart FormData requests with file parts use the native uploader; other requests continue through the existing adapter. If the native handler is unavailable, the wrapper is not installed.

Toggling useNativeMultipartUpload back to false does not uninstall an adapter that was already installed on that client. Create a new client if you need to switch adapter behavior at runtime.

To override ImageComponent or the chat LoadingIndicator, use WithComponents:

<WithComponents
  overrides={{ ImageComponent: FastImage, ChatLoadingIndicator: MyLoader }}
>
  <Chat client={client}>...</Chat>
</WithComponents>