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, and if you use React Navigation place OverlayProvider above NavigationContainer, 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 WithComponents overrides (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 the following contexts, accessible via their hooks:

• ImageGalleryContext via useImageGalleryContext
• OverlayContext via useOverlayContext
• ThemeContext via useTheme
• TranslationContext via useTranslationContext

Props

| value | Partially overrides the value provided to the OverlayContext. Can be used to set the theme via the style key. | object |

Customizing Overlay Components

Image gallery subcomponents and the message overlay background are overridden via WithComponents:

<WithComponents
  overrides={{
    ImageGalleryHeader: MyGalleryHeader,
    ImageGalleryFooter: MyGalleryFooter,
    ImageGalleryGrid: MyGalleryGrid,
    ImageGalleryVideoControls: MyVideoControls,
    MessageOverlayBackground: MyOverlayBackground,
  }}
>
  <OverlayProvider>...</OverlayProvider>
</WithComponents>

Custom Message Actions Overlay

The MessageActions override replaces the entire message overlay action block (top, message, and bottom hosts) rendered by MessageOverlayHostLayer. When provided, it receives animated layout styles:

const CustomMessageActions = ({
  topItemStyle,
  hostStyle,
  bottomItemStyle,
  portalHostStyle,
}) => (
  <Animated.View style={hostStyle}>
    {/* Your custom overlay content */}
  </Animated.View>
);

<WithComponents overrides={{ MessageActions: CustomMessageActions }}>
  <OverlayProvider>...</OverlayProvider>
</WithComponents>;

Examples

Customizing value with a theme

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

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