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 subcomponents via imageGalleryCustomComponents 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 AttachmentPickerContext, 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.

imageGalleryCustomComponents

ImageGallery renders the image viewer and handles zoom/swipe gestures. You can't replace the whole component, but you can replace subcomponents via imageGalleryCustomComponents. Each key maps to a subcomponent and its props are spread onto that component.

• footer -> ImageGalleryFooter
• grid -> ImageGrid
• gridHandle -> ImageGridHandle
• header -> ImageGalleryHeader

imageGalleryGridHandleHeight

Height of the image gallery grid bottom sheet handle.

imageGalleryGridSnapPoints

The SnapPoints for the image gallery grid bottom sheet.

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