Image

Components/Media

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

Overview

Copy

Images communicate product information to users with visuals.

Do

  • Use them to display images like product thumbnails.

Don't

  • Don't display photos of users. Use <Avatar/> instead.
  • Don't display images that can be uploaded, updated or removed. Use a built-in <ImageViewer/> solution instead.

Feature examples

Dimensions

Specify image dimensions in pixels or percentage with width and height props.

Copy

Border

To separate images from backgrounds, enable the image bordershowBorder.

Copy

Border radius

Control the rounded corners of the image box with the borderRadius prop. Radius levels can be specified for every corner.

Copy

States

Use the src prop to display a link to a media file. If the src prop is added without a link, the default placeholder shows.

Copy

Background fill

To remove the background color for PNG images or vector graphics, use the transparent prop.

Copy

Fit mode

Control how images are displayed when their dimensions don't match the size of their containers with the fit prop. It supports all default object-fit values, but there are four that are most commonly used:

  • contain maintains the aspect ratio while fitting images within containers.
  • cover maintains the aspect ratio and clips images to fill containers.
  • none loads the original image size and positions it in the center of the container.
  • tile repeats images when their dimensions are smaller than the containers.
Copy

Position

Control image placement inside of a bounding box with the position property. Specify the starting position of the image from where its fit will be defined.

Copy

Common use case examples

Mixed border radius

Use images with mixed corner radius levels in cases when they touch the edges of cards.

Copy

Product list

Use images to display product thumbnails in lists and widgets.

Copy

Accessibility examples

Alt text

By default, all images have empty alt text.

  • For decorative images, leave alt text empty.
  • For informative images that need to be described to screen readers, add alt text which describes the image in context.
  • For images that have links, the alt text should also tell the screen reader where the link goes.

Use this alt decision tree to determine whether an image needs alt text.

Copy

Code

Copy

Props

NameTypeDefaultDescription
altstring''Specifies an alt text for an image. If not provided, it is set to empty and treated as decorative.
borderRadiusstring | number | string & {}—Sets the border radius of the image box.
dataHookstring—Applies a data-hook HTML attribute that can be used in the tests.
fit"none" | "fill" | "contain" | "cover" | "scale-down" | "tile"coverSpecifies image fit mode inside a box. tile repeats the image, and the other values set the CSS object-fit property.
heightstring | numberundefinedSets the height of the image box.
positionstringcenterSpecifies source content position inside of an image box. Accepts any valid CSS position value, for example center or top left.
showBorderbooleanfalseSpecifies whether to display a border around an image.
srcstring—Specifies an URL link to image source. If not provided, a default placeholder image is displayed.
transparentbooleanfalseSpecifies whether background of Image is transparent.
widthstring | number'100%'Sets the width of the image box.

Testkit

Import the driver matching your test environment:

Copy

Driver methods

MethodDescription
isTransparentChecks whether background of Image is transparent
existsChecks whether the component found with the given data hook.
elementGets the component root element.
clickClicks on the component root element.
baseReturns UniDriver for the base element.

Changelog

  • 1.340.0 (2026-10-21) — maintenance release, no component-specific 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.330.3 (2026-09-29) — maintenance release, no component-specific changes
  • 1.329.0 (2026-09-24) — 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.310.0 (2026-08-10) — maintenance release, no component-specific changes
  • 1.292.0 (2026-06-22) — maintenance release, no component-specific changes
  • 1.291.0 (2026-06-19) — maintenance release, no component-specific changes
  • 1.266.0 (2026-04-07) — maintenance release, no component-specific changes
  • 1.260.0 (2026-03-17) — maintenance release, no component-specific changes
  • 1.222.0 (2025-10-23) — fix: add missing "scale-down" "fit" prop value (#15431)
  • 1.198.0 (2025-06-09) — maintenance release, no component-specific changes
  • 1.194.0 (2025-05-30) — breaking: tokenization (#14902)
  • 1.138.1 (2024-10-30) — 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.93.0 (2024-02-08) — 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?