# Attachments

`Attachment` renders the attachments for a message and chooses the UI based on each attachment shape.

## Best Practices

- Keep custom attachment logic focused on the types you actually use.
- Prefer the supported override points on `Attachment` instead of customizing low-level attachment containers directly.
- Combine `message.shared_location` with `message.attachments` when you render `Attachment` inside a fully custom message UI.
- Use CDN-backed sizing and the SDK sizing handlers for images and videos whenever possible.
- Treat native `giphy` messages as their own attachment surface; they render through `Giphy`, not `ModalGallery`.
- Test messages with mixed attachment types so your custom layout still behaves well.

## Default Rendering

`Attachment` groups message attachments before rendering them. The default UI surface is:

| Attachment shape                 | Default UI                                                                                                                              |
| -------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------- |
| audio attachment                 | [Audio](https://github.com/GetStream/stream-chat-react/blob/master/src/components/Attachment/Audio.tsx)                                 |
| scraped content / OG attachment  | [Card](https://github.com/GetStream/stream-chat-react/blob/master/src/components/Attachment/LinkPreview/Card.tsx)                       |
| file attachment                  | [FileAttachment](https://github.com/GetStream/stream-chat-react/blob/master/src/components/Attachment/FileAttachment.tsx)               |
| giphy attachment                 | [Giphy](https://github.com/GetStream/stream-chat-react/blob/master/src/components/Attachment/Giphy.tsx)                                 |
| shared location                  | [Geolocation](https://github.com/GetStream/stream-chat-react/blob/master/src/components/Attachment/Geolocation.tsx)                     |
| single image attachment          | [Image](https://github.com/GetStream/stream-chat-react/blob/master/src/components/Attachment/Image.tsx)                                 |
| single video attachment          | [VideoPlayer](https://github.com/GetStream/stream-chat-react/blob/master/src/components/VideoPlayer/VideoPlayer.tsx)                    |
| multiple image/video attachments | [ModalGallery](https://github.com/GetStream/stream-chat-react/blob/master/src/components/Attachment/ModalGallery.tsx)                   |
| voice recording attachment       | [VoiceRecording](https://github.com/GetStream/stream-chat-react/blob/master/src/components/Attachment/VoiceRecording.tsx)               |
| unsupported attachment           | [UnsupportedAttachment](https://github.com/GetStream/stream-chat-react/blob/master/src/components/Attachment/UnsupportedAttachment.tsx) |

Attachments with `og_scrape_url` or `title_link` are rendered as scraped content cards. Shared location is read from `message.shared_location`, not from `message.attachments`.

Native `giphy` attachments render inline through `Giphy`. They do not open `ModalGallery`; the gallery viewer is used for image and mixed image/video gallery content. If you want a modal or fullscreen experience for sent giphies, override `Giphy` directly.

## Unsupported attachments

When the SDK cannot map an attachment to a supported renderer (for example an empty object, an unknown `type`, or a custom shape you have not wired through your own `Attachment` override), it uses [`UnsupportedAttachment`](https://github.com/GetStream/stream-chat-react/blob/master/src/components/Attachment/UnsupportedAttachment.tsx).

## Basic Usage

The default SDK message UI already renders `Attachment` for you. If you build your own message component, render it with the current message attachments:

```tsx
import { Attachment, MessageText, useMessageContext } from "stream-chat-react";

const CustomMessage = () => {
  const { message } = useMessageContext();
  const attachments = [
    ...(message.shared_location ? [message.shared_location] : []),
    ...(message.attachments ?? []),
  ];

  return (
    <div>
      <MessageText />
      {attachments.length ? <Attachment attachments={attachments} /> : null}
    </div>
  );
};
```

## UI Customization

The supported media override points are:

- `Image` for a single image attachment
- `Media` for a single video attachment
- `ModalGallery` for multi-image or mixed image/video galleries

You can also replace `AttachmentActions`, `Audio`, `Card`, `File`, `Geolocation`, `Giphy`, `UnsupportedAttachment`, and `VoiceRecording`.

### Customizing `Attachment` inside your own message UI

If you render `Attachment` directly, pass the custom subcomponents you need:

```tsx
import {
  Attachment,
  type AttachmentProps,
  type ModalGalleryProps,
  type VideoPlayerProps,
} from "stream-chat-react";

const CustomVideoPlayer = ({ thumbnailUrl, videoUrl }: VideoPlayerProps) => (
  <video controls poster={thumbnailUrl} src={videoUrl} />
);

const CustomModalGallery = ({ items }: ModalGalleryProps) => (
  <div className="custom-gallery-grid">
    {items.map((item, index) => {
      const previewUrl = item.imageUrl ?? item.videoThumbnailUrl;
      if (!previewUrl) return null;

      return (
        <button key={index}>
          <img alt={item.alt ?? "attachment"} src={previewUrl} />
        </button>
      );
    })}
  </div>
);

const CustomAttachment = (props: AttachmentProps) => (
  <Attachment
    {...props}
    Media={CustomVideoPlayer}
    ModalGallery={CustomModalGallery}
  />
);
```

### Replacing the SDK attachment renderer

If you want the SDK `Message`, `VirtualMessage`, and thread surfaces to use your attachment renderer, register it with `WithComponents`:

```tsx
import {
  Channel,
  MessageComposer,
  MessageList,
  WithComponents,
} from "stream-chat-react";

const App = () => (
  <WithComponents overrides={{ Attachment: CustomAttachment }}>
    <Channel>
      <MessageList />
      <MessageComposer />
    </Channel>
  </WithComponents>
);
```

<admonition type="tip">

If you customized low-level attachment containers in earlier versions, prefer these v14-supported surfaces first: `Attachment`, `Image`, `Media`, `ModalGallery`, `File`, `Card`, `Giphy`, `Geolocation`, `VoiceRecording`, `UnsupportedAttachment`, and `AttachmentActions`.

</admonition>

## Image And Video Sizing

The SDK computes image and video dimensions from CSS and the channel sizing handlers.

### Maximum size

Use [`--str-chat__attachment-max-width`](/chat/docs/sdk/react/theming/component-variables/) to control the maximum width and height used by image and video attachments. The value must resolve to pixels through [`getComputedStyle`](https://developer.mozilla.org/en-US/docs/Web/API/Window/getComputedStyle), for example `300px`, `10rem`, or `calc(300px - var(--margin))`.

If the value does not resolve to a pixel value, attachment sizing can break and message-list scroll behavior can become inaccurate.

### File size optimization

The default image and video renderers use the attachment dimensions together with Stream's CDN so the SDK can request a smaller asset when possible.

### Aspect ratio

The SDK preserves aspect ratio when it can, but cropping can still happen when:

1. the message layout forces the attachment to fill the available width
2. Safari stretches portrait media to the configured max width
3. the host element's size constraints cannot fit the source without cropping

<admonition type="tip">

If you use your own CDN or custom media sizing rules, provide your own [`imageAttachmentSizeHandler`](/chat/docs/sdk/react/components/core-components/channel#imageattachmentsizehandler/) and [`videoAttachmentSizeHandler`](/chat/docs/sdk/react/components/core-components/channel#videoattachmentsizehandler/) on `Channel`.

</admonition>

## Props

| Prop                            | Description                                                                                                                                                                                                                                                                                                          | Type                                                                                                   |
| ------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------ |
| `actionHandler`                 | Attachment action handler.                                                                                                                                                                                                                                                                                           | `(dataOrName?: string \| FormData, value?: string, event?: React.BaseSyntheticEvent) => Promise<void>` |
| `AttachmentActions`             | Component used to render attachment actions. Defaults to [AttachmentActions](https://github.com/GetStream/stream-chat-react/blob/master/src/components/Attachment/AttachmentActions.tsx).                                                                                                                            | `component`                                                                                            |
| `attachmentActionsDefaultFocus` | Controls the default focused action per attachment type. Defaults to `{ giphy: "send" }`.                                                                                                                                                                                                                            | `AttachmentActionsDefaultFocusByType`                                                                  |
| `attachments`                   | Message attachments to render.                                                                                                                                                                                                                                                                                       | `(Attachment \| SharedLocationResponse)[]`                                                             |
| `Audio`                         | Component used to render audio attachments. Defaults to [Audio](https://github.com/GetStream/stream-chat-react/blob/master/src/components/Attachment/Audio.tsx).                                                                                                                                                     | `component`                                                                                            |
| `Card`                          | Component used to render link-preview cards. Defaults to [Card](https://github.com/GetStream/stream-chat-react/blob/master/src/components/Attachment/LinkPreview/Card.tsx).                                                                                                                                          | `component`                                                                                            |
| `File`                          | Component used to render file attachments. Defaults to [FileAttachment](https://github.com/GetStream/stream-chat-react/blob/master/src/components/Attachment/FileAttachment.tsx).                                                                                                                                    | `component`                                                                                            |
| `Geolocation`                   | Component used to render geolocation attachments. Defaults to [Geolocation](https://github.com/GetStream/stream-chat-react/blob/master/src/components/Attachment/Geolocation.tsx).                                                                                                                                   | `component`                                                                                            |
| `Giphy`                         | Component used to render giphy attachments. Defaults to [Giphy](https://github.com/GetStream/stream-chat-react/blob/master/src/components/Attachment/Giphy.tsx).                                                                                                                                                     | `component`                                                                                            |
| `Image`                         | Component used to render image attachments. Defaults to [Image](https://github.com/GetStream/stream-chat-react/blob/master/src/components/Attachment/Image.tsx).                                                                                                                                                     | `component`                                                                                            |
| `isQuoted`                      | Renders the attachment in quoted-message mode.                                                                                                                                                                                                                                                                       | `boolean`                                                                                              |
| `Media`                         | Component used to render media attachments. Defaults to [VideoPlayer](https://github.com/GetStream/stream-chat-react/blob/master/src/components/VideoPlayer/VideoPlayer.tsx).                                                                                                                                        | `component`                                                                                            |
| `ModalGallery`                  | Component used to render the attachment gallery modal. Defaults to [ModalGallery](https://github.com/GetStream/stream-chat-react/blob/master/src/components/Attachment/ModalGallery.tsx).                                                                                                                            | `component`                                                                                            |
| `UnsupportedAttachment`         | Component used when the SDK cannot choose a more specific attachment renderer. Defaults to [UnsupportedAttachment](https://github.com/GetStream/stream-chat-react/blob/master/src/components/Attachment/UnsupportedAttachment.tsx); uses `AttachmentFileIcon` from `ComponentContext` for the icon (same as `File`). | `component`                                                                                            |
| `VoiceRecording`                | Component used to render voice-recording attachments. Defaults to [VoiceRecording](https://github.com/GetStream/stream-chat-react/blob/master/src/components/Attachment/VoiceRecording.tsx).                                                                                                                         | `component`                                                                                            |


---

This page was last updated at 2026-05-13T13:38:54.750Z.

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