# OverlayProvider

The `OverlayProvider` is the top level Stream Chat for React Native component and wraps all other components provided by the SDK.
The `OverlayProvider` allows users to interact with messages on long press above the underlying views, use the full screen image viewer, and use the `AttachmentPicker` as a keyboard-esk view.

## Basic Usage

The `OverlayProvider` should wrap all other Stream Chat for React Native components and in most cases the majority of your application.

<admonition type="note">

For detailed implementation instructions of the `OverlayProvider` with navigation please refer to the [Stream Chat with Navigation](/chat/docs/sdk/react-native/v4/basics/stream-chat-with-navigation/).

</admonition>

```tsx {7,11}
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` contains providers for the `AttachmentPickerContext`, `ImageGalleryContext`, `MessageOverlayContext`, `OverlayContext`, `ThemeContext`, and `TranslationContext`.
These can be accessed using the corresponding hooks.

| Context                   | Hook                         |
| ------------------------- | ---------------------------- |
| `AttachmentPickerContext` | `useAttachmentPickerContext` |
| `ImageGalleryContext`     | `useImageGalleryContext`     |
| `MessageOverlayContext`   | `useMessageOverlayContext`   |
| `OverlayContext`          | `useOverlayContext`          |
| `ThemeContext`            | `useTheme`                   |
| `TranslationContext`      | `useTranslationContext`      |

## UI Customizations

You can override any of the components rendered in overlay using props on `OverlayProvider` or `Channel`.
Custom components provided to `Channel` are hoisted to the overlay for use in displaying messages within the `OverlayProvider`.
Customizing these components requires no interaction with the `OverlayProvider`.

Components only rendered within the overlay can be overridden and modified via props on the `OverlayProvider`.
Removing the `OverlayReactionList` can be done easily by replacing it with a function that returns null.

```tsx
<OverlayProvider OverlayReactionList={() => null}>
```

<tabs>

<tabs-item value="message-overlay" label="Message Overlay">

![](@chat-sdk/react-native/v4/_assets/api-references/components/overlay-provider/visual_guide_1.png)

</tabs-item>

<tabs-item value="image-picker" label="Image Picker">

![](@chat-sdk/react-native/v4/_assets/api-references/components/overlay-provider/visual_guide_2.png)

</tabs-item>

<tabs-item value='image-gallery'>

![](@chat-sdk/react-native/v4/_assets/api-references/components/overlay-provider/visual_guide_3.png)

</tabs-item>

</tabs>

## Props

The `OverlayProvider` can be used with no props provided but there are a plethora of props for customizing the components in the overlay.

### attachmentPickerBottomSheetHandleHeight

Height of the image picker bottom sheet handle.

| Type   | Default |
| ------ | ------- |
| number | 20      |


### attachmentPickerBottomSheetHeight

Height of the image picker bottom sheet when closed.

| Type   | Default |
| ------ | ------- |
| number | 308     |


### attachmentPickerErrorButtonText

Text for the button within [`AttachmentPickerError`](/chat/docs/sdk/react-native/v4/core-components/overlay-provider#attachmentpickererror/) that opens the apps OS level settings.

| Type   | Default                        |
| ------ | ------------------------------ |
| string | "Allow access to your Gallery" |


### attachmentPickerErrorText

Error text for [`AttachmentPickerError`](/chat/docs/sdk/react-native/v4/core-components/overlay-provider#attachmentpickererror/).

| Type   | Default                                                                 |
| ------ | ----------------------------------------------------------------------- |
| string | "Please enable access to your photos and videos so you can share them." |


### attachmentSelectionBarHeight

Height of the attachment selection bar displayed above the image picker.

| Type   | Default |
| ------ | ------- |
| number | 52      |


### `bottomInset`

Height of items located below the `MessageInput` when present.
This inset determines the underlying shift to the `MessageList` when it is opened.

<admonition type="tip">

This can also be set via the `setBottomInset` function provided by the `useAttachmentPickerContext` hook.

</admonition>

| Type   | Default |
| ------ | ------- |
| number | 0       |

### giphyVersion

The Giphy version to render when viewing a Giphy in the Image Gallery.
Check the keys of the [Image Object](https://developers.giphy.com/docs/api/schema#image-object) for possible values.

| Type   | Default        |
| ------ | -------------- |
| string | 'fixed_height' |


### i18nInstance

Instance of `Streami18n` class used for internationalization.
Please read more in the [translations docs](/chat/docs/sdk/react-native/v4/basics/translations/) for details on creation and customization.

| Type                                                                |
| ------------------------------------------------------------------- |
| [`Streami18n`](/chat/docs/sdk/react-native/v4/basics/translations/) |


### imageGalleryCustomComponents

[Image gallery](/chat/docs/sdk/react-native/v4/ui-components/image-gallery/) components.
Each key in the object is spread as props onto its respective component.
Each component has a number of sub-components it can receive in this manor.

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

[`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]` |


### messageTextNumberOfLines

Number of lines for the message text in the Message Overlay.

| Type   | Default |
| ------ | ------- |
| number | 5       |


### numberOfAttachmentImagesToLoadPerCall

Number of images to load per call to [`CameraRoll.getPhotos`](https://github.com/react-native-cameraroll/react-native-cameraroll#getphotos).

| Type   | Default |
| ------ | ------- |
| number | 60      |


### numberOfAttachmentPickerImageColumns

Number of columns to render within the image picker.

| Type   | Default |
| ------ | ------- |
| number | 3       |


### numberOfImageGalleryGridColumns

Number of columns to render within the image gallery grid.

| Type   | Default |
| ------ | ------- |
| number | 3       |


### `topInset`

Distance from the top of the screen the attachment picker should open to when expanded.
This is often set to the header height.

<admonition type="tip">

This can also be set via the `setTopInset` function provided by the `useAttachmentPickerContext` hook.

</admonition>

| Type   | Default |
| ------ | ------- |
| number | 0       |

### value

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

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

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

| Type   |
| ------ |
| object |


### AttachmentPickerBottomSheetHandle

Bottom sheet handle component for image picker.

| Type      | Default                                                                                                                                                                                       |
| --------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| component | [AttachmentPickerBottomSheetHandle](https://github.com/GetStream/stream-chat-react-native/blob/main/package/src/components/AttachmentPicker/components/AttachmentPickerBottomSheetHandle.tsx) |


### AttachmentPickerError

Error component displayed when the app doesn't have permissions to access photos on the device.

| Type      | Default                                                                                                                                                               |
| --------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| component | [AttachmentPickerError](https://github.com/GetStream/stream-chat-react-native/blob/main/package/src/components/AttachmentPicker/components/AttachmentPickerError.tsx) |


### AttachmentPickerErrorImage

Image component within [`AttachmentPickerError`](/chat/docs/sdk/react-native/v4/core-components/overlay-provider#attachmentpickererror/).

| Type      | Default                                                                                                                                                                         |
| --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| component | [AttachmentPickerErrorImage](https://github.com/GetStream/stream-chat-react-native/blob/main/package/src/components/AttachmentPicker/components/AttachmentPickerErrorImage.tsx) |


### CameraSelectorIcon

Camera selector component displayed in the attachment selector bar.

| Type      | Default                                                                                                                                                         |
| --------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| component | [CameraSelectorIcon](https://github.com/GetStream/stream-chat-react-native/blob/main/package/src/components/AttachmentPicker/components/CameraSelectorIcon.tsx) |


### FileSelectorIcon

File selector component displayed in the attachment selector bar.

| Type      | Default                                                                                                                                                     |
| --------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- |
| component | [FileSelectorIcon](https://github.com/GetStream/stream-chat-react-native/blob/main/package/src/components/AttachmentPicker/components/FileSelectorIcon.tsx) |


### ImageOverlaySelectedComponent

Indicator component used to designate an image as selected in the image picker.

| Type      | Default                                                                                                                                                                               |
| --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| component | [ImageOverlaySelectedComponent](https://github.com/GetStream/stream-chat-react-native/blob/main/package/src/components/AttachmentPicker/components/ImageOverlaySelectedComponent.tsx) |


### ImageSelectorIcon

Image selector component displayed in the attachment selector bar.

| Type      | Default                                                                                                                                                       |
| --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| component | [ImageSelectorIcon](https://github.com/GetStream/stream-chat-react-native/blob/main/package/src/components/AttachmentPicker/components/ImageSelectorIcon.tsx) |


### MessageActionList

Component for rendering a message action list within the message overlay.

| Type      | Default                                                                                                                                           |
| --------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |
| Component | [[MessageActionList](https://github.com/GetStream/stream-chat-react-native/blob/main/package/src/components/MessageOverlay/MessageActionList.tsx) |


### MessageActionListItem

Component for rendering message action list items within a message action list.

| Type      | Default                                                                                                                                                  |
| --------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Component | [MessageActionListItem](https://github.com/GetStream/stream-chat-react-native/blob/main/package/src/components/MessageOverlay/MessageActionListItem.tsx) |


### OverlayReactionList

Reaction selector component displayed within the message overlay when user long presses a message.

| Type      | Default                                                                                    |
| --------- | ------------------------------------------------------------------------------------------ |
| component | [OverlayReactionList](/chat/docs/sdk/react-native/v4/ui-components/overlay-reaction-list/) |


### OverlayReactions

List of reactions component within the message overlay.

| Type      | Default                                                                             |
| --------- | ----------------------------------------------------------------------------------- |
| component | [OverlayReactions](/chat/docs/sdk/react-native/v4/ui-components/overlay-reactions/) |


### OverlayReactionsAvatar

Component for rendering a avatar in the message reaction overlay.

| Type      | Default                                                                                          |
| --------- | ------------------------------------------------------------------------------------------------ |
| component | [OverlayReactionsAvatar](/chat/docs/sdk/react-native/v4/ui-components/overlay-reactions-avatar/) |



---

This page was last updated at 2026-07-10T16:05:06.276Z.

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