Skip to main content
Migrate to Polaris

Version 2025-07 is the last API version to support React-based UI components. Later versions use web components, native UI elements with built-in accessibility, better performance, and consistent styling with Shopify's design system. Check out the migration guide to upgrade your extension.

Image

Image is used for large format, responsive images.

Support
Targets (50)

Supported targets

Anchor to ExamplesExamples

Anchor to Basic ImageBasic Image

Basic Image

Example

Basic Image

import {
reactExtension,
Image,
} from '@shopify/ui-extensions-react/checkout';

export default reactExtension(
'purchase.checkout.block.render',
() => <Extension />,
);

function Extension() {
return (
<Image source="https://cdn.shopify.com/YOUR_IMAGE_HERE" />
);
}
import {extension, Image} from '@shopify/ui-extensions/checkout';

export default extension('purchase.checkout.block.render', (root) => {
const image = root.createComponent(Image, {
source: 'https://cdn.shopify.com/YOUR_IMAGE_HERE',
});

root.appendChild(image);
});

Anchor to PropertiesProperties

Anchor to imagepropsImageProps

Image is used for large format, responsive images.

Anchor to source
source
Required< < string, < & > > >
required

The URL of the image to display. Supports remote URLs and local file resources. You can also use conditional styles with resolution and viewportInlineSize conditions to serve different images based on the device's pixel density or viewport width.

Anchor to accessibilityDescription
accessibilityDescription
string
Default: ''

The alternative text that describes the image for assistive technologies. Screen readers announce this text when they encounter the image, and it displays as a fallback if the image fails to load.

Learn more about writing effective alternative text.

Anchor to accessibilityRole
accessibilityRole
'decorative'

The semantic role of the image for assistive technologies.

  • decorative: Marks the image as purely visual, so screen readers skip it entirely. Use this for images that don’t convey meaningful content (like background patterns or visual flourishes).
Anchor to aspectRatio
aspectRatio
number

The aspect ratio to display the image at (fills the width of the parent container and sets the height accordingly). An invisible placeholder is created to prevent content jumping when the image loads. Use along with fit if the specified aspect ratio does not match the intrinsic aspect ratio to prevent the image from stretching.

Anchor to border
border
<<>>

The border style of the element.

To shorten the code, it is possible to specify all the border style properties in one property.

For example:

  • base means blockStart, inlineEnd, blockEnd and inlineStart border styles are base

  • ['base', 'none'] means blockStart and blockEnd border styles are base, inlineStart and inlineEnd border styles are none

  • ['base', 'none', 'dotted', 'base'] means blockStart border style is base, inlineEnd border style is none, blockEnd border style is dotted and blockStart border style is base

Anchor to borderWidth
borderWidth
< <> >

The border width of the element.

To shorten the code, it is possible to specify all the border width properties in one property.

For example:

  • base means blockStart, inlineEnd, blockEnd and inlineStart border widths are base

  • ['base', 'medium'] means blockStart and blockEnd border widths are base, inlineStart and inlineEnd border widths are medium

  • ['base', 'medium', 'medium', 'base'] means blockStart border width is base, inlineEnd border width is medium, blockEnd border width is medium and blockStart border width is base

Anchor to cornerRadius
cornerRadius
< <> >

The corner radius of the element.

Provide a single value to apply the same corner radius to all four corners, two values to apply different corner radii to opposing corners, or four values to apply different corner radii to each individual corner.

For example:

  • base means all 4 corner radii are base

  • ['base', 'none'] means the StartStart and EndEnd corner radii are base, StartEnd and EndStart corner radii are none. When the context’s language direction is left to right, StartStart and EndEnd corners are the top left and bottom right corners while StartEnd and EndStart corners are the top right and bottom left corners.

  • ['base', 'none', 'small', 'base'] means StartStart corner radius is base, StartEnd corner radius is none, EndEnd corner radius is small and EndStart corner radius is base

A borderRadius alias is available for this property. When both are specified, cornerRadius takes precedence.

Anchor to fit
fit
<>

The fit of the image within its frame. Use when the image is not displayed at its intrinsic size to maintain the aspect ratio.

Anchor to id
id
string

A unique identifier for the component.

Anchor to loading
loading

The loading strategy for the image. Uses native browser behavior and is not supported by all browsers. If no value is provided, the image is loaded immediately.

Anchor to borderRadius
borderRadius
< <> >
Deprecated

Use cornerRadius instead.

The corner radius of the element. Accepts a single value for all corners or a shorthand tuple for per-corner control.

Anchor to LoadingLoading

ValueDescription
"eager"Image is loaded immediately, regardless of whether or not the image is currently within the visible viewport.
"lazy"Image is loaded when it’s within the visible viewport.
Was this page helpful?