# OverlayProvider

> **Info:** This is release candidate documentation for **Stream Chat React Native SDK v10**. For the latest stable version, see the [latest version (v9)](https://getstream.io/chat/docs/sdk/react-native/).

`OverlayProvider` goes around `Chat` and your navigation. It renders your app, and on top of it a layer for the message menu that opens on a long press and, while it's open, the image gallery. It also provides the theme, translations and accessibility configuration that those overlays, and everything else below it, read. [Overlays and bottom sheets](https://getstream.io/chat/docs/sdk/react-native/v10/ui/customizing/overlays-and-bottom-sheets/#overlayprovider) explains what opens where.

## Best practices

- Render one `OverlayProvider` at the root of the app, above `Chat` and your `NavigationContainer`, so its layer covers the whole window, headers and tab bars included.
- Give a screen in another native window, such as a React Native `Modal`, an `OverlayProvider` of its own inside the modal. See [Chat in modals](https://getstream.io/chat/docs/sdk/react-native/v10/ui/layout/chat-in-modals/).
- Pass the same theme to `value.style` and to `Chat`'s `style`, and the same `Streami18n` instance to both `i18nInstance` props.
- Put overrides for the keys `OverlayProvider` renders, such as `ImageGalleryHeader` and `MessageOverlayBackground`, in a `WithComponents` around it. See [Where to put WithComponents](https://getstream.io/chat/docs/sdk/react-native/v10/ui/customizing/overriding-components/#where-to-put-withcomponents).

## Basic usage

```tsx title="App.tsx"
import { NavigationContainer } from "@react-navigation/native";
import type { PropsWithChildren } from "react";
import { GestureHandlerRootView } from "react-native-gesture-handler";
import type { StreamChat } from "stream-chat";
import { Chat, OverlayProvider } from "stream-chat-react-native";

export const AppRoot = ({
  children,
  client,
}: PropsWithChildren<{ client: StreamChat }>) => (
  <GestureHandlerRootView style={{ flex: 1 }}>
    <OverlayProvider>
      <Chat client={client}>
        <NavigationContainer>{children}</NavigationContainer>
      </Chat>
    </OverlayProvider>
  </GestureHandlerRootView>
);
```

## What it provides

From the outside in, `OverlayProvider` renders these providers around your app:

- `TranslationContext`, from `i18nInstance`. Its `userLanguage` is `en`; `Chat` provides the connected user's language to the components below it.
- `AccessibilityContext`, from `accessibility`.
- [`OverlayContext`](https://getstream.io/chat/docs/sdk/react-native/v10/component-reference/chat/overlaycontext/), with which overlay is open.
- `ImageGalleryContext`, from the gallery props.
- `ThemeContext`, from `value.style` merged over the default theme.
- The portal host that the message menu moves a message into.

When the image gallery is open, the Android back button closes it.

## Props

| Prop                              | Type                                     | Default                                       | Description                                                                                                                                                                                                                                                                              |
| --------------------------------- | ---------------------------------------- | --------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `accessibility`                   | `AccessibilityConfig`                    | accessibility off                             | The opt-in accessibility layer: screen-reader announcements, gesture alternatives and accessibility attributes. `{ enabled: true }` turns it on. See [Accessibility](https://getstream.io/chat/docs/sdk/react-native/v10/features/app-experience/accessibility/).                                            |
| `autoPlayVideo`                   | `boolean`                                | `false`                                       | Whether a video starts playing when the gallery opens on it.                                                                                                                                                                                                                             |
| `giphyVersion`                    | `keyof NonNullable<Attachment['giphy']>` | `'fixed_height'`                              | The rendition of a Giphy the gallery shows, one of the keys of a Giphy attachment's `giphy` object. Read once, when `OverlayProvider` mounts. The message list takes its own `giphyVersion` from `Channel`.                                                                              |
| `i18nInstance`                    | `Streami18n`                             | an English instance `OverlayProvider` creates | The dictionaries and date formatting of what `OverlayProvider` renders, such as the gallery's header. Pass the instance you give `Chat`. See [Localization](https://getstream.io/chat/docs/sdk/react-native/v10/ui/customizing/localization/#streami18n).                                                    |
| `numberOfImageGalleryGridColumns` | `number`                                 | `3`                                           | The number of columns of the gallery's grid of every image and video.                                                                                                                                                                                                                    |
| `value`                           | `Partial<OverlayContextValue>`           |                                               | `value.style` is the theme for everything below, merged over the default theme. `value.overlay` sets the overlay open on mount. The other keys of `OverlayContextValue` are ignored. See [Setting the theme](https://getstream.io/chat/docs/sdk/react-native/v10/ui/customizing/theming/#setting-the-theme). |

`OverlayProvider` also renders its `children`.

## Examples

### Theme, translations and accessibility

```tsx title="App.tsx"
import type { PropsWithChildren } from "react";
import type { StreamChat } from "stream-chat";
import { Chat, OverlayProvider, Streami18n } from "stream-chat-react-native";
import type {
  AccessibilityConfig,
  DeepPartial,
  Theme,
} from "stream-chat-react-native";

// Declared once, at module scope, so the providers get the same objects on every render.
const theme: DeepPartial<Theme> = {
  semantics: { accentPrimary: "#0d47a1" },
};
const overlayValue = { style: theme };
const streami18n = new Streami18n();
const accessibility: AccessibilityConfig = { enabled: true };

export const ChatRoot = ({
  children,
  client,
}: PropsWithChildren<{ client: StreamChat }>) => (
  <OverlayProvider
    accessibility={accessibility}
    i18nInstance={streami18n}
    numberOfImageGalleryGridColumns={4}
    value={overlayValue}
  >
    <Chat client={client} i18nInstance={streami18n} style={theme}>
      {children}
    </Chat>
  </OverlayProvider>
);
```

`value` is passed on to the context in a new object on every render, but the theme is merged again only when `value.style` changes, so keep that object stable.

## Related hooks

| Hook                        | Returns                                                                                                                                  |
| --------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- |
| `useOverlayContext()`       | the [`OverlayContext`](https://getstream.io/chat/docs/sdk/react-native/v10/component-reference/chat/overlaycontext/) value; throws outside `OverlayProvider` |
| `useTheme()`                | `{ theme }`, the merged theme                                                                                                            |
| `useTranslationContext()`   | `t`, `tDateTimeParser` and `userLanguage`                                                                                                |
| `useAccessibilityContext()` | the resolved accessibility configuration                                                                                                 |
| `useImageGalleryContext()`  | the gallery props and the gallery's state store                                                                                          |

---

For the most recent version of this documentation, visit [https://getstream.io/chat/docs/sdk/react-native/v10/component-reference/chat/overlayprovider/](https://getstream.io/chat/docs/sdk/react-native/v10/component-reference/chat/overlayprovider/).