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.

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

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

PropDescriptionType
clientStream Chat client instance.StreamChat
closeConnectionOnBackgroundWhen 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
enableOfflineSupportEnables 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. Defaults to false.boolean
useNativeMultipartUploadWhen 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
i18nInstanceStreami18n instance for internationalization. See translations docs.Streami18n
styleA 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
isMessageAIGeneratedA 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>
Previous
OverlayContext
Next
ChatContext