# Gallery

Renders image attachments inside [`MessageList`](/chat/docs/sdk/react-native/ui-components/message-list/).

## Best Practices

- Keep gallery layouts compact to avoid oversized rows.
- Use `setOverlay` and gallery context helpers instead of custom image viewers.
- Handle mixed image/video attachments gracefully.
- Respect `preventPress` when you need to disable full-screen viewing.
- Avoid heavy image processing in render; rely on caching or native components.

## Basic Usage

Replace the default UI via `WithComponents`.

```tsx
import { WithComponents, Gallery } from "stream-chat-react-native";

<WithComponents overrides={{ Gallery: () => <Gallery preventPress /> }}>
  <Channel channel={channel}>
    <MessageList />
    <MessageComposer />
  </Channel>
</WithComponents>;
```

## Props

| Prop                              | Description                                                                                                                                                                                                                                                                         | Type                                                             |
| --------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------- |
| `additionalPressableProps`        | Extra props passed to the underlying [Pressable](https://reactnative.dev/docs/pressable#props) used in message components like [`MessageContent`](/chat/docs/sdk/react-native/ui-components/message-content/).                                                                      | `object`                                                         |
| `alignment`                       | Sets whether the message aligns left or right in the list. Defaults to `'right'`.                                                                                                                                                                                                   | `enum('right', 'left')`                                          |
| `groupStyles`                     | Position of the message within a group of consecutive messages from the same user. Use `groupStyles` to style messages based on position (for example, avatars show only on the last message).                                                                                      | `array of enum('top', 'bottom', 'middle', 'single')`             |
| `hasThreadReplies`                | Whether the current message has thread replies. Used to set the correct bottom corner radius based on alignment. Defaults to `!!message.reply_count`.                                                                                                                               | `boolean`                                                        |
| `images`                          | Array of `image` attachments on the message.                                                                                                                                                                                                                                        | `array`                                                          |
| `legacyImageViewerSwipeBehaviour` | Enable/disable legacy image viewer behavior. When true, the image viewer lets you swipe through all loaded images in the channel, adding JS thread work. Available in SDK version >= [v3.9.0](https://github.com/GetStream/stream-chat-react-native/releases). Defaults to `false`. | `boolean`                                                        |
| `messageId`                       | ID of the current message.                                                                                                                                                                                                                                                          | `string`                                                         |
| `messageText`                     | Text content of the current message (`message.text`). Used for gallery styling.                                                                                                                                                                                                     | `string`                                                         |
| `onLongPress`                     | Default long press handler for message UI.                                                                                                                                                                                                                                          | `function`                                                       |
| `onPress`                         | Default press handler for message UI.                                                                                                                                                                                                                                               | `function`                                                       |
| `onPressIn`                       | Default `pressIn` handler for message UI.                                                                                                                                                                                                                                           | `function`                                                       |
| `preventPress`                    | If true, disables `onPress`. Defaults to `false`.                                                                                                                                                                                                                                   | `boolean`                                                        |
| `setSelectedMessage`              | Setter for value [`selectedMessage`](/chat/docs/sdk/react-native/contexts/image-gallery-context#selectedmessage/).                                                                                                                                                                  | `(selectedMessage: {messageId?: string; url?: string;}) => void` |
| `setMessages`                     | Setter for value [`messages`](/chat/docs/sdk/react-native/contexts/image-gallery-context#messages/).                                                                                                                                                                                | `(messages: LocalMessage[]) => void`                             |
| `setOverlay`                      | Setter for [`overlay`](/chat/docs/sdk/react-native/contexts/overlay-context#overlay/). You can use this setter to show the overlay.                                                                                                                                                 | `(overlay) => void`                                              |
| `threadList`                      | True if the current message is part of a thread.                                                                                                                                                                                                                                    | `boolean`                                                        |
| `videos`                          | Array of `video` attachments.                                                                                                                                                                                                                                                       | `array`                                                          |

## UI Component Props

| Prop                         | Description                                                                                                                                                  | Type            |
| ---------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ | --------------- |
| `AttachmentUploadIndicator`  | Renders pending upload progress over local image and video thumbnails. Defaults to `AttachmentUploadIndicator`.                                              | `ComponentType` |
| `MediaUploadProgressOverlay` | Renders the full-cover upload overlay used by `AttachmentUploadIndicator` in overlay mode. Defaults to `MediaUploadProgressOverlay`.                         | `ComponentType` |
| `VideoThumbnail`             | Renders video thumbnails for video attachments in `MessageList`. Defaults to [`VideoThumbnail`](/chat/docs/sdk/react-native/ui-components/video-thumbnail/). | `ComponentType` |


---

This page was last updated at 2026-07-13T13:43:06.830Z.

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