Skip to main content

Image

The image component embeds images within the interface with control over presentation and loading behavior. Use image to visually illustrate concepts, showcase products, display user content, or support tasks and interactions with visual context.

Images support responsive sizing, alt text for accessibility, aspect ratio control, and loading states for progressive enhancement. For small preview images in lists or tables, use thumbnail. For profile images, use avatar.

Support
Targets (29)

Supported targets

  • purchase.checkout.actions.render-before
  • purchase.checkout.block.render
  • purchase.checkout.cart-line-item.render-after
  • purchase.checkout.cart-line-list.render-after
  • purchase.checkout.contact.render-after
  • purchase.checkout.delivery-address.render-after
  • purchase.checkout.delivery-address.render-before
  • purchase.checkout.footer.render-after
  • purchase.checkout.header.render-after
  • purchase.checkout.payment-method-list.render-after
  • purchase.checkout.payment-method-list.render-before
  • purchase.checkout.pickup-location-list.render-after
  • purchase.checkout.pickup-location-list.render-before
  • purchase.checkout.pickup-location-option-item.render-after
  • purchase.checkout.pickup-point-list.render-after
  • purchase.checkout.pickup-point-list.render-before
  • purchase.checkout.reductions.render-after
  • purchase.checkout.reductions.render-before
  • purchase.checkout.shipping-option-item.details.render
  • purchase.checkout.shipping-option-item.render-after
  • purchase.checkout.shipping-option-list.render-after
  • purchase.checkout.shipping-option-list.render-before
  • purchase.thank-you.announcement.render
  • purchase.thank-you.block.render
  • purchase.thank-you.cart-line-item.render-after
  • purchase.thank-you.cart-line-list.render-after
  • purchase.thank-you.customer-information.render-after
  • purchase.thank-you.footer.render-after
  • purchase.thank-you.header.render-after

Anchor to accessibilityRole
accessibilityRole
'img' | 'none' | 'presentation'
Default: 'img'

Sets the semantic meaning of the image content. When set, the role will be used by assistive technologies to help users navigate the page.

  • 'img': Identifies the element as an image that conveys meaningful information to users.
  • 'none': Completely hides the element and its content from assistive technologies.
  • 'presentation': Removes semantic meaning, making the image purely decorative and ignored by screen readers.
string
Default: ''

Alternative text that describes the image for accessibility.

Provides a text description of the image for users with assistive technology and serves as a fallback when the image fails to load. A well-written description enables people with visual impairments to understand non-text content.

When a screen reader encounters an image, it reads this description aloud. When an image fails to load, this text displays on screen, helping all users understand what content was intended.

Learn more about writing effective alt text and the alt attribute.

Anchor to aspectRatio
aspectRatio
`${number}${optionalSpace}/${optionalSpace}${number}` | `${number}`
Default: '1/1'

The aspect ratio of the image.

The rendering of the image will depend on the inlineSize value:

  • inlineSize="fill": the aspect ratio will be respected and the image will take the necessary space.
  • inlineSize="auto": the image will not render until it has loaded and the aspect ratio will be ignored.

Learn more about the aspect-ratio property.

Anchor to border
border
Default: 'none' - equivalent to `none base auto`.

A shorthand for setting the border around the image. Accepts a size keyword alone (for example, 'base'), a size and color (for example, 'base base'), or a size, color, and style (for example, 'base base solid'). Use 'none' to remove the border.

Anchor to borderRadius
borderRadius
<Extract<$1['borderRadius'], 'none' | 'small-100' | 'small' | 'base' | 'large' | 'large-100' | 'max'>>
Default: 'none'

The radius of the border corners around the image. You can use a single value to apply the same radius to all corners, or use the 1-to-4-value syntax to control individual corners.

Anchor to borderStyle
borderStyle
<> | ""
Default: '' - meaning no override

Controls the visual style of the border on all sides, such as solid, dashed, or dotted.

When set, this overrides the style value specified in the border property.

Supports 1-to-4-value syntax for specifying different styles per side:

  • One value: applies to all sides
  • Two values: applies to block sides (top/bottom) and inline sides (left/right) respectively
  • Three values: applies to block-start (top), inline sides (left/right), and block-end (bottom) respectively
  • Four values: applies to block-start (top), inline-end (right), block-end (bottom), and inline-start (left) respectively
Anchor to borderWidth
borderWidth
<> | ''
Default: '' - meaning no override

The width of the border around the image. You can use a single value to apply the same width to all sides, or use the 1-to-4-value syntax to control individual sides. When set, this overrides the width value specified in the border shorthand.

string

A unique identifier for the element. Use this to reference the element in JavaScript, link labels to form controls, or target specific elements for styling or scripting.

Anchor to inlineSize
inlineSize
'fill' | 'auto'
Default: 'fill'

The inline width (horizontal size) of the image.

  • 'fill': The image takes up 100% of the available inline space.
  • 'auto': The image is displayed at its natural size.

Learn more about the width attribute.

Anchor to loading
loading
'eager' | 'lazy'
Default: 'eager'

Determines the loading behavior of the image:

  • 'eager': Immediately loads the image, irrespective of its position within the visible viewport.
  • 'lazy': Delays loading the image until it approaches a specified distance from the viewport.

Learn more about the loading attribute.

Anchor to objectFit
objectFit
'contain' | 'cover'
Default: 'contain'

How the image should be resized to fit its container. The image is positioned in the center of the container. Learn more about the object-fit property.

  • 'contain': Fits the entire image within the container, preserving aspect ratio. May leave empty space.
  • 'cover': Fills the container while preserving aspect ratio, cropping the image if needed.
Anchor to sizes
sizes
string

A set of media conditions and their corresponding sizes. Learn more about the sizes attribute.

string

The image source (either a remote URL or a local file resource).

When the image is loading or no src is provided, a placeholder is rendered. Learn more about the src attribute.

Anchor to srcSet
srcSet
string

A set of image sources and their width or pixel density descriptors. Learn more about the srcset attribute. This overrides the src property.

Examples
<s-image src="https://cdn.shopify.com/YOUR_IMAGE_HERE" alt="Product image"></s-image>

Preview

  • Use high-resolution images to ensure a professional and high-quality experience.
  • Use optimized images so your app loads as fast as possible.
  • Use images intentionally, these should add clarity and lead users to the next step.
Was this page helpful?