OverlayProvider

OverlayProvider is the top-level Stream Chat React Native component. It wraps all other SDK components and enables long-press message actions and the full-screen image viewer.

Best Practices

• Wrap your entire app (or top navigation tree) to avoid context mismatches.
• Keep OverlayProvider stable; avoid re-mounting it on screen changes.
• Use the provided hooks instead of prop drilling for overlay contexts.
• Customize image gallery subcomponents via dedicated component props (ImageGalleryHeader, ImageGalleryFooter, ImageGalleryGrid, ImageGalleryVideoControls) rather than replacing the full image viewer.
• Pass theming via value.style to keep UI consistent across screens.

General Usage

Wrap all Stream Chat components with OverlayProvider (usually the whole app).

Note: For navigation details, see the Navigation guide.

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

const client = StreamChat.getInstance("api_key");

export const App = () => (
  <OverlayProvider>
    <Chat client={client}>
      <ChannelList />
    </Chat>
  </OverlayProvider>
);

Context Providers

OverlayProvider provides ImageGalleryContext, OverlayContext, ThemeContext, and TranslationContext. Use the corresponding hooks to access them.

Props

autoPlayVideo

Enable or disable autoplay for overlay videos.

giphyVersion

Giphy image rendition to use in the Image Gallery. See the Image Object keys for options.

i18nInstance

Streami18n instance used for internationalization. See the translations docs for setup and customization.

ImageGalleryFooter

Custom component to render as the image gallery footer. Receives ImageGalleryFooterProps.

ImageGalleryGrid

Custom component to render the image gallery grid. Receives ImageGalleryGridProps.

ImageGalleryHeader

Custom component to render as the image gallery header. Receives ImageGalleryHeaderProps.

ImageGalleryVideoControls

Custom component to render the video controls within the image gallery. Receives ImageGalleryVideoControlProps.

MessageOverlayBackground

Custom backdrop component rendered behind overlay content in MessageOverlayHostLayer.

numberOfImageGalleryGridColumns

Number of columns to render within the image gallery grid.

value

Partially overrides the value provided to the OverlayContext. This prop can be used to set the theme via the style key.

const theme = {
  messageSimple: {
    file: {
      container: {
        backgroundColor: "red",
      },
    },
  },
};

<OverlayProvider value={{ style: theme }}>...</OverlayProvider>;