# 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](/chat/docs/sdk/react-native/basics/stream_chat_with_navigation/).**

```tsx
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.

| Context                                                                                                                                                      | Hook                   |
| ------------------------------------------------------------------------------------------------------------------------------------------------------------ | ---------------------- |
| [`ImageGalleryContext`](https://github.com/GetStream/stream-chat-react-native/blob/develop/package/src/contexts/imageGalleryContext/ImageGalleryContext.tsx) | useImageGalleryContext |
| [`OverlayContext`](https://github.com/GetStream/stream-chat-react-native/blob/develop/package/src/contexts/overlayContext/OverlayContext.tsx)                | useOverlayContext      |
| [`ThemeContext`](https://github.com/GetStream/stream-chat-react-native/blob/develop/package/src/contexts/themeContext/ThemeContext.tsx)                      | useTheme               |
| [`TranslationContext`](https://github.com/GetStream/stream-chat-react-native/blob/develop/package/src/contexts/translationContext/TranslationContext.tsx)    | useTranslationContext  |

## Props

### `autoPlayVideo`

Enable or disable autoplay for overlay videos.

| Type    | Default |
| ------- | ------- |
| Boolean | false   |

### `giphyVersion`

Giphy image rendition to use in the Image Gallery. See the [Image Object](https://developers.giphy.com/docs/api/schema#image-object) keys for options.

| Type   | Default        |
| ------ | -------------- |
| String | 'fixed_height' |

### `i18nInstance`

`Streami18n` instance used for internationalization. See the [translations docs](/chat/docs/sdk/react-native/basics/translations/) for setup and customization.

| Type                                                                                               |
| -------------------------------------------------------------------------------------------------- |
| [`Streami18n`](https://www.notion.so/Internationalization-67ad5785c9734be6bebe33cd9ea7d060?pvs=21) |

### `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](https://github.com/GetStream/stream-chat-react-native/blob/main/package/src/components/ImageGallery/components/ImageGalleryFooter.tsx)
- `grid` -> [ImageGrid](https://github.com/GetStream/stream-chat-react-native/blob/main/package/src/components/ImageGallery/components/ImageGrid.tsx)
- `gridHandle` -> [ImageGridHandle](https://github.com/GetStream/stream-chat-react-native/blob/main/package/src/components/ImageGallery/components/ImageGridHandle.tsx)
- `header` -> [ImageGalleryHeader](https://github.com/GetStream/stream-chat-react-native/blob/main/package/src/components/ImageGallery/components/ImageGalleryHeader.tsx)

| Type   |
| ------ |
| Object |

### `imageGalleryGridHandleHeight`

Height of the image gallery grid bottom sheet handle.

| Type   | Default |
| ------ | ------- |
| Number | 40      |

### `imageGalleryGridSnapPoints`

The [`SnapPoints`](https://gorhom.github.io/react-native-bottom-sheet/props#snappoints) for the image gallery grid bottom sheet.

| Type  | Default                        |
| ----- | ------------------------------ |
| Array | `[0, (screenHeight * 9) / 10]` |

### `numberOfImageGalleryGridColumns`

Number of columns to render within the image gallery grid.

| Type   | Default |
| ------ | ------- |
| Number | 3       |

### `value`

Partially overrides the `value` provided to the `OverlayContext`. This prop can be used to set the [theme](/chat/docs/sdk/react-native/customization/theming/) via the `style` key.

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

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

| Type   |
| ------ |
| Object |


---

This page was last updated at 2026-03-12T08:52:33.164Z.

For the most recent version of this documentation, visit [https://getstream.io/chat/docs/sdk/react-native/core-components/overlay-provider/](https://getstream.io/chat/docs/sdk/react-native/core-components/overlay-provider/).