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
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

To override ImageComponent or the chat LoadingIndicator, use WithComponents:

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