ImageViewer

Components/Media

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

Overview

Copy

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.

Copy

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.
Copy

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/>.

Copy

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.
Copy

Border radius

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

Copy

Disabled

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

Customize the tooltip's style with all common tooltipProps.

Copy

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.

Copy

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.

Copy

Code

Copy

Props

NameTypeDefaultDescription
addImageInfostring'Add Image'Specifies a message to display in a tooltip when no image is uploaded yet.
altstring''Specifies an alt text for an image. If not provided, it is set to empty and treated as decorative.
dataHookstring—Applies a data-hook HTML attribute that can be used in the tests.
disabledboolean—Specifies whether the component is disabled.
downloadImageInfostring'Download'Defines a message to display in a tooltip when 'Download' action button is hovered.
errorboolean—Displays the image in an error state.
errorMessagestring—Sets the message shown in the error state.
fit"contain" | "cover"coverSpecifies image fit mode inside a box by setting the CSS object-fit property.
heightstring | number—Sets the height of the viewer box.
imagePropsPick<ImageProps, "style" | "borderRadius" | "width" | "height" | "transparent" | "alt" | "position" | "showBorder">—Additional props to pass to the Image component (borderRadius, position, showBorder, transparent, etc.).
imageUrlstring—Links to image asset source (URL). Leave it blank when image isn't uploaded yet.
moreImageInfostring'More actions'Defines a message to display in a tooltip when the 'More' action button is hovered. Relevant only when all buttons are visible.
onAddImageMouseEventHandler—Defines a click handler, which is called every time a user clicks on an empty viewer (when no imageUrl is provided).
onDownloadImageMouseEventHandler—Defines a handler function, which is called every time user clicks on the download button.
onImageLoadReactEventHandler<HTMLImageElement>—Defines a handler function which is called right after image loads.
onRemoveImageMouseEventHandler—Defines a handler function, which is called every time user clicks on the 'Remove image' button.
onUpdateImageMouseEventHandler—Defines a handler function, which is called every time user clicks on the 'Update image' button.
removeButtonAriaLabelstring—Defines a string value that labels the remove button element.
removeImageInfostring'Remove'Defines a message to display in a tooltip, when 'remove' action button is hovered.
removeRoundedBordersboolean—Removes default border radius.
showDownloadButtonbooleanfalseSpecifies whether the download button is visible.
showRemoveButtonbooleantrueSpecifies whether the remove button is visible.
showUpdateButtonbooleantrueSpecifies whether the update button is visible.
status"error" | "warning" | "loading"—Specifies the status of a viewer.
statusMessageReactNode—Defines the message to display on status icon hover. If not given or empty, no tooltip is displayed.
tooltipPropsTooltipCommonProps—Allows to pass all common tooltip props.
updateButtonAriaLabelstring—Defines a string value that labels the update button element.
updateImageInfostring'Update'Defines a message to display in a tooltip when 'Update' action button is hovered.
widthstring | 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) — 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)
  • 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) — 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)
  • 1.232.0 (2025-11-28) — fix: add interface for imageProps (#15548)
  • 1.221.0 (2025-10-15) — fix: isImageLoaded testkit method (#15411)
  • 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)
  • 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

Last updated: 22 October 2026

Did this help?