Components/Media
Interactive docs page: https://wix-pages.com/design-system-documentation/#/component/imageviewer
Image viewers let users display images with built-in functions like upload, update and remove.
<Image/> instead.Specify the component's dimensions in pixels or by percentage using the width and height properties.
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.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.
<FormField/> and add the statusMessage.statusMessage prop. Control tooltip placement with tooltipPlacement prop.View more inline status message examples in <FormField/>.
Supports two states:
<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.imageUrl prop to pass a link to a media file.Remove default corner radius with the removeRoundedBorders prop. Use it when component is used as a part of another widget.
Disable all viewer interactions with the disabled prop. Use it to highlight unavailable functions.
Customize the tooltip's style with all common tooltipProps.
Control which actions are visible with the showUpdateButton, showDownloadButton and showRemoveButton props. Tooltip messages explaining the actions can be customized according to their need.
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.
| 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. |
No testkit for this component — it doesn't expose a unidriver testkit.
imageProps (#15548)Last updated: 22 October 2026