# BaseImage

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

`BaseImage` is the `<img>` the SDK renders images with. When an image fails to load, it renders `ImagePlaceholder` in its place, and it tries again when `src` changes. It cleans `src` with [`@braintree/sanitize-url`](https://github.com/braintree/sanitize-url), so a `javascript:` URL never loads. [Attachments and uploads](https://getstream.io/chat/docs/sdk/react/v15/features/rich-content/attachments-and-uploads/) explains how attachments render.

The `BaseImage` override key reaches:

- the images and image galleries in messages;
- Giphy attachments;
- the image previews in the composer;
- the media in channel details.

Link-preview cards, quoted messages, the composer's link previews, video thumbnails and the full-screen gallery render the SDK's `BaseImage` directly, so the key doesn't reach them. `ImagePlaceholder` is read by `BaseImage` itself, so its override reaches every image.

![A failed image attachment: the placeholder with the retry button](https://getstream.io/docs-assets/images/f83d9ea88cba.png)

![An image gallery with one image that failed to load](https://getstream.io/docs-assets/images/ebcfa4cd0d7a.png)

![ImagePlaceholder in the composer's attachment preview](https://getstream.io/docs-assets/images/75fda269d965.png)

## Best practices

- To change what a broken image shows, override `ImagePlaceholder` rather than `BaseImage`. It reaches every image.
- In a replacement for `BaseImage`, forward the `ref` and pass `onLoad` and `onError` on. The SDK measures images through the ref to request the right size, and the gallery shows its loading and retry states from the two events.
- Keep a replacement compatible with plain `<img>` props: the SDK passes `alt`, `src`, `style`, `width`, `height` and class names.

## Usage

### Custom image fallback

`ImagePlaceholder` receives a `className`, which carries `str-chat__base-image--load-failed` and the classes the image had. Keep it so the placeholder takes the image's place in the layout:

```tsx
import type { ImagePlaceholderProps } from "stream-chat-react";
import { WithComponents } from "stream-chat-react";

const UnavailableImage = ({ className }: ImagePlaceholderProps) => (
  <div className={className} role="img">
    Image unavailable
  </div>
);

const overrides = { ImagePlaceholder: UnavailableImage };

export const App = () => (
  <WithComponents overrides={overrides}>
    {/* the rest of the app */}
  </WithComponents>
);
```

### Custom BaseImage

This replacement keeps the default and loads images lazily:

```tsx
import { forwardRef } from "react";
import type { BaseImageProps } from "stream-chat-react";
import { BaseImage, WithComponents } from "stream-chat-react";

const LazyBaseImage = forwardRef<HTMLImageElement, BaseImageProps>(
  function LazyBaseImage(props, ref) {
    return <BaseImage {...props} loading="lazy" ref={ref} />;
  },
);

const overrides = { BaseImage: LazyBaseImage };

export const App = () => (
  <WithComponents overrides={overrides}>
    {/* the rest of the app */}
  </WithComponents>
);
```

## Props

`BaseImage` takes every `<img>` prop and a `ref`. `alt` defaults to `''`. It also takes:

| Prop                        | Type      | Default | Description                                                        |
| --------------------------- | --------- | ------- | ------------------------------------------------------------------ |
| `showDownloadButtonOnError` | `boolean` | `false` | Renders a button that downloads the image next to the placeholder. |

`ImagePlaceholder` takes one prop:

| Prop        | Type     | Default | Description                                                         |
| ----------- | -------- | ------- | ------------------------------------------------------------------- |
| `className` | `string` |         | The failed image's classes and `str-chat__base-image--load-failed`. |

The default placeholder shows the `IconImage` icon, with the label "Image failed to load" for screen readers.

---

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