> To build a Wix site agentically, or add Wix features like bookings or a store to a site you already have, follow https://www.wix.com/headless/skill.md
> 
> Portal Navigation:
> 
> - Append `.md` to any URL under `https://dev.wix.com/docs/` to get its markdown version.
> - Pages are either content pages (article or reference text) or menu pages (a list of links to child pages).
> - To get a menu page, truncate any URL to a parent path and append `.md` (e.g. `https://dev.wix.com/docs/sdk.md`, `https://dev.wix.com/docs/sdk/core-modules.md`).
> - If a reference page seems to be missing its schema (parameters, return types, or type definitions), append `?schema=true` to its `.md` URL (e.g. `https://dev.wix.com/docs/contexts/contexts/stores/category-info/use-category-info-context.md?schema=true`).
> - Top-level index of all portals: https://dev.wix.com/docs/llms.txt
> - Full concatenated docs: https://dev.wix.com/docs/llms-full.txt

## Resource: ImageViewer Component

## Article: ImageViewer Component

## Article Link: https://dev.wix.com/docs/wix-design-system/components/media/image-viewer-component.md

## Article Content:

# ImageViewer

_Components/Media_

Interactive docs page: <https://wix-pages.com/design-system-documentation/#/component/imageviewer>

## Overview

```jsx
<Box align="center">
  <ImageViewer imageUrl="TravelExample3.jpg" />
</Box>;
```

Image viewers let users display images with built-in functions like upload, update and remove.

### Do

- Use them to upload images, such as event covers.
- Use them to display images that can be updated or removed.

### Don't

- Don't use them to display images that aren't interactive. Use static `<Image/>` instead.

### Feature examples

#### Dimensions

Specify the component's dimensions in pixels or by percentage using the `width` and `height` properties.

```jsx
<ImageViewer width="35%" height="240px" />;
```

#### Status

Control the component's status using the `status` prop. It supports three states:

- `error` indicates when an image failed to upload.
- `warning` highlights that the media can't be validated.
- `loading` shows that the media file is loading.

```jsx
<StorybookComponents.Stack>
  <ImageViewer status="error" />
  <ImageViewer status="warning" />
  <ImageViewer status="loading" />
</StorybookComponents.Stack>;
```

#### Status message

Add text that explains the status or what action the user should take with the `statusMessage` prop.

Showing the status message inline, directly below the image viewer is preferred in all default cases.

- To add an accessible inline message, wrap the component in a `<FormField/>` and add the `statusMessage`.
- To add a status message in a tooltip that requires users to hover on the icon, use the `statusMessage` prop. Control tooltip placement with `tooltipPlacement` prop.

View more inline status message examples in `<FormField/>`.

```jsx
<StorybookComponents.Stack flexDirection="column">
  <StorybookComponents.Stack flexDirection="column" gap="12px">
    <Text secondary>For all default cases:</Text>
    <FormField status="error" statusMessage="This is an error message.">
      <ImageViewer />
    </FormField>
  </StorybookComponents.Stack>
  <StorybookComponents.Stack flexDirection="column" gap="12px">
    <Text secondary>For narrow layouts only:</Text>
    <ImageViewer status="error" statusMessage="This is an error message." />
  </StorybookComponents.Stack>
</StorybookComponents.Stack>;
```

#### States

Supports two states:

- No image source - uses `<AddItem/>` component to upload media in a required way. Use `addImageInfo` to specify a message to display in a tooltip when users hover over the component.
- With image source - use `imageUrl` prop to pass a link to a media file.

```jsx
<StorybookComponents.Stack>
  <ImageViewer />
  <ImageViewer imageUrl="example.jpg" />
</StorybookComponents.Stack>;
```

#### Border radius

Remove default corner radius with the `removeRoundedBorders` prop. Use it when component is used as a part of another widget.

```jsx
<ImageViewer imageUrl="example.jpg" removeRoundedBorders />;
```

#### Disabled

Disable all viewer interactions with the `disabled` prop. Use it to highlight unavailable functions.

Customize the tooltip's style with all common `tooltipProps`.

```jsx
<ImageViewer disabled addImageInfo="Message explaining disabled item status" />;
```

#### Actions

Control which actions are visible with the `showUpdateButton`, `showDownloadButton` and `showRemoveButton` props. Tooltip messages explaining the actions can be customized according to their need.

```jsx
<ImageViewer
  imageUrl="example.jpg"
  showUpdateButton={true}
  showDownloadButton={true}
  showRemoveButton={true}
  updateImageInfo="Change image"
  downloadImageInfo="Download image"
  removeImageInfo="Delete image"
  moreImageInfo="More actions"
/>;
```

### Common use case examples

#### Form

Use image viewer in forms where only a single image can be uploaded at a time, e.g., a cover for an event, group or program.

```jsx
<Card>
  <Card.Header title="Program info" />
  <Card.Divider />
  <Card.Content>
    <Layout>
      <Cell span={8}>
        <Box direction="vertical" gap="12px">
          <FormField label="Program name" required>
            <Input value="Sugar Reset" />
          </FormField>
          <FormField label="Description">
            <InputArea
              value="Want to feel better, have more energy and trim down your waistline at the same time? Removing refined and added sugar from your diet is for you!"
              resizable
              maxLength={100}
              hasCounter
              minHeight="120px"
            />
          </FormField>
        </Box>
      </Cell>
      <Cell span={4}>
        <FormField label="Cover image">
          <ImageViewer imageUrl="FoodExample1.jpg" height="218px" />
        </FormField>
      </Cell>
    </Layout>
  </Card.Content>
</Card>;
```

## Code

```jsx
import { ImageViewer } from '@wix/design-system';
```

### Props

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `addImageInfo` | `string` | `'Add Image'` | Specifies a message to display in a tooltip when no image is uploaded yet. |
| `alt` | `string` | `''` | Specifies an alt text for an image. If not provided, it is set to empty and treated as decorative. |
| `dataHook` | `string` | — | Applies a data-hook HTML attribute that can be used in the tests. |
| `disabled` | `boolean` | — | Specifies whether the component is disabled. |
| `downloadImageInfo` | `string` | `'Download'` | Defines a message to display in a tooltip when 'Download' action button is hovered. |
| `error` | `boolean` | — | Displays the image in an error state. |
| `errorMessage` | `string` | — | Sets the message shown in the error state. |
| `fit` | `"contain" \| "cover"` | ``cover`` | Specifies image fit mode inside a box by setting the CSS `object-fit` property. |
| `height` | `string \| number` | — | Sets the height of the viewer box. |
| `imageProps` | `Pick<ImageProps, "style" \| "borderRadius" \| "width" \| "height" \| "transparent" \| "alt" \| "position" \| "showBorder">` | — | Additional props to pass to the Image component (borderRadius, position, showBorder, transparent, etc.). |
| `imageUrl` | `string` | — | Links to image asset source (URL). Leave it blank when image isn't uploaded yet. |
| `moreImageInfo` | `string` | `'More actions'` | Defines a message to display in a tooltip when the 'More' action button is hovered. Relevant only when all buttons are visible. |
| `onAddImage` | `MouseEventHandler` | — | Defines a click handler, which is called every time a user clicks on an empty viewer (when no `imageUrl` is provided). |
| `onDownloadImage` | `MouseEventHandler` | — | Defines a handler function, which is called every time user clicks on the download button. |
| `onImageLoad` | `ReactEventHandler<HTMLImageElement>` | — | Defines a handler function which is called right after image loads. |
| `onRemoveImage` | `MouseEventHandler` | — | Defines a handler function, which is called every time user clicks on the 'Remove image' button. |
| `onUpdateImage` | `MouseEventHandler` | — | Defines a handler function, which is called every time user clicks on the 'Update image' button. |
| `removeButtonAriaLabel` | `string` | — | Defines a string value that labels the remove button element. |
| `removeImageInfo` | `string` | `'Remove'` | Defines a message to display in a tooltip, when 'remove' action button is hovered. |
| `removeRoundedBorders` | `boolean` | — | Removes default border radius. |
| `showDownloadButton` | `boolean` | `false` | Specifies whether the download button is visible. |
| `showRemoveButton` | `boolean` | `true` | Specifies whether the remove button is visible. |
| `showUpdateButton` | `boolean` | `true` | Specifies whether the update button is visible. |
| `status` | `"error" \| "warning" \| "loading"` | — | Specifies the status of a viewer. |
| `statusMessage` | `ReactNode` | — | Defines the message to display on status icon hover. If not given or empty, no tooltip is displayed. |
| `tooltipProps` | `TooltipCommonProps` | — | Allows to pass all common tooltip props. |
| `updateButtonAriaLabel` | `string` | — | Defines a string value that labels the update button element. |
| `updateImageInfo` | `string` | `'Update'` | Defines a message to display in a tooltip when 'Update' action button is hovered. |
| `width` | `string \| number` | — | Sets the width of the viewer box. |

## Testkit

No testkit for this component — it doesn't expose a unidriver testkit.

## Changelog

- **1.340.0** (2026-10-21) — fix: the More actions button stays light secondary while its menu is open, in every theme. In Harmony (odeditor), ImageViewer also has 12px rounded corners and a blurred tinted overlay on hover, and error and warning statuses show only the coloured border, without an icon on the image. ([#17461](invalid-url)) — has visual changes
- **1.339.0** (2026-10-19) — maintenance release, no component-specific changes
- **1.338.0** (2026-10-15) — maintenance release, no component-specific changes
- **1.336.0** (2026-10-13) — maintenance release, no component-specific changes
- **1.332.0** (2026-10-05) — maintenance release, no component-specific changes
- **1.330.3** (2026-09-29) — maintenance release, no component-specific changes
- **1.330.0** (2026-09-28) — maintenance release, no component-specific changes
- **1.329.0** (2026-09-24) — maintenance release, no component-specific changes
- **1.328.0** (2026-09-22) — maintenance release, no component-specific changes
- **1.325.0** (2026-09-17) — maintenance release, no component-specific changes
- **1.324.0** (2026-09-14) — maintenance release, no component-specific changes
- **1.323.0** (2026-09-10) — maintenance release, no component-specific changes
- **1.310.0** (2026-08-10) — maintenance release, no component-specific changes
- **1.293.0** (2026-06-26) — feat: add alt prop ([#16442](invalid-url))
- **1.292.0** (2026-06-22) — maintenance release, no component-specific changes
- **1.278.0** (2026-05-08) — maintenance release, no component-specific changes
- **1.273.0** (2026-04-30) — maintenance release, no component-specific changes
- **1.266.0** (2026-04-07) — maintenance release, no component-specific changes
- **1.262.0** (2026-03-25) — fix: hide add image ui while image is loading ([#16056](invalid-url)) — has visual changes
- **1.260.0** (2026-03-17) — maintenance release, no component-specific changes
- **1.247.2** (2026-01-21) — maintenance release, no component-specific changes
- **1.241.0** (2025-12-17) — maintenance release, no component-specific changes
- **1.240.0** (2025-12-16) — maintenance release, no component-specific changes
- **1.238.0** (2025-12-10) — feat: add aria-label props for the buttons ([#15647](invalid-url))
- **1.232.0** (2025-11-28) — fix: add interface for `imageProps` ([#15548](invalid-url))
- **1.221.0** (2025-10-15) — fix: isImageLoaded testkit method ([#15411](invalid-url))
- **1.220.2** (2025-10-06) — maintenance release, no component-specific changes
- **1.212.0** (2025-08-11) — maintenance release, no component-specific changes
- **1.197.0** (2025-06-06) — breaking: tokenization ([#14909](invalid-url))
- **1.165.0** (2025-02-27) — maintenance release, no component-specific changes
- **1.156.0** (2025-01-29) — maintenance release, no component-specific changes
- **1.138.1** (2024-10-30) — maintenance release, no component-specific changes
- **1.128.0** (2024-09-19) — maintenance release, no component-specific changes
- **1.115.0** (2024-07-17) — maintenance release, no component-specific changes
- **1.102.0** (2024-04-16) — maintenance release, no component-specific changes
- **1.92.1** (2024-02-05) — maintenance release, no component-specific changes