Choose a version:

Image

Image is used for large format, responsive images.

Support

Targets (50)

Supported targets

Checkout::Actions::RenderBefore
Checkout::CartLineDetails::RenderAfter
Checkout::CartLines::RenderAfter
Checkout::Contact::RenderAfter
Checkout::CustomerInformation::RenderAfter
Checkout::DeliveryAddress::RenderBefore
Checkout::Dynamic::Render
Checkout::PickupLocations::RenderAfter
Checkout::PickupLocations::RenderBefore
Checkout::PickupPoints::RenderAfter
Checkout::PickupPoints::RenderBefore
Checkout::Reductions::RenderAfter
Checkout::Reductions::RenderBefore
Checkout::ShippingMethodDetails::RenderAfter
Checkout::ShippingMethodDetails::RenderExpanded
Checkout::ShippingMethods::RenderAfter
Checkout::ShippingMethods::RenderBefore
Checkout::ThankYou::CartLineDetails::RenderAfter
Checkout::ThankYou::CartLines::RenderAfter
Checkout::ThankYou::CustomerInformation::RenderAfter
Checkout::ThankYou::Dynamic::Render
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 ExamplesExamples

Anchor to Basic ImageBasic Image

Basic Image

Basic Image

import {

reactExtension,

Image,

} from '@shopify/ui-extensions-react/checkout';

export default reactExtension(

'purchase.checkout.block.render',

() => <Extension />,

);

function Extension() {

return (

);

}

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);

});

React

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" />
  );
}

JS

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

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. Accepts a single value for all four edges, or a shorthand tuple for per-edge control:

'base': Applies base to all edges.

['base', 'none']: Block edges get base, inline edges get none.

['base', 'none', 'dotted', 'base']: Values apply to block-start, inline-end, block-end, and inline-start respectively.
Anchor to borderWidth borderWidth < <> >: The border width of the element. Accepts a single value for all four edges, or a shorthand tuple for per-edge control:

'base': Applies base to all edges.

['base', 'medium']: Block edges get base, inline edges get medium.

['base', 'medium', 'medium', 'base']: Values apply to block-start, inline-end, block-end, and inline-start respectively.
Anchor to cornerRadius cornerRadius < <> >: The corner radius of the element. Accepts a single value for all four corners, or a shorthand tuple for per-corner control using logical (writing-mode-aware) corners:

'base': All four corners get base radius.

['base', 'none']: StartStart/EndEnd get base, StartEnd/EndStart get none. In left-to-right mode, StartStart and EndEnd are the top-left and bottom-right corners.

['base', 'none', 'small', 'base']: Values apply to StartStart, StartEnd, EndEnd, and EndStart respectively.

A borderRadius alias is available. When both are set, 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. Use this to target the component in scripts or stylesheets, or to distinguish it from other instances of the same 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 < <> >: The corner radius of the element. Accepts a single value for all four corners, or a shorthand tuple for per-corner control:

'base': All four corners get base radius.

['base', 'none']: StartStart/EndEnd get base, StartEnd/EndStart get none.

['base', 'none', 'small', 'base']: Values apply to StartStart, StartEnd, EndEnd, and EndStart respectively.

Deprecated
Use cornerRadius instead.

MaybeResponsiveConditionalStyle

A type that represents a value that can be a conditional style. The conditions are based on the viewport size. We highly recommend using the `Style` helper which simplifies the creation of conditional styles.

T | ConditionalStyle<T, ViewportSizeCondition>

ConditionalStyle

A conditional style definition that maps one or more conditions to different values. The `default` value is used as a fallback when none of the conditions in `conditionals` are satisfied.

conditionals
An array of conditional values.
```
ConditionalValue<T, AcceptedConditions>[]
```
default
The default value applied when none of the conditional values specified in `conditionals` are met.
```
T
```

ConditionalValue

A single conditional branch that pairs a set of conditions with the value to apply when those conditions are met.

conditions
The conditions that must be met for the value to be applied. At least one condition must be specified.
```
AcceptedConditions
```
value
The value that will be applied if the conditions are met.
```
T
```

ViewportSizeCondition

A condition that targets layouts based on the inline size (width in horizontal writing modes) of the viewport.

viewportInlineSize
The minimum viewport inline size that the condition must match.
```
{ min: T; }
```

MaybeShorthandProperty

A type that accepts either a single value applied to all edges or a shorthand tuple for per-edge control. - `T`: A single value applied uniformly to all edges. - `[T, T]`: The first value applies to block-start and block-end, the second to inline-start and inline-end. - `[T, T, T, T]`: Values apply to block-start, inline-end, block-end, and inline-start respectively.

T | ShorthandProperty<T>

ShorthandProperty

A tuple type that accepts two or four values following the CSS shorthand convention for box edges. - `[T, T]`: The first value applies to block-start and block-end, the second to inline-start and inline-end. - `[T, T, T, T]`: Values apply to block-start, inline-end, block-end, and inline-start respectively.

[T, T] | [T, T, T, T]

BorderStyle

A keyword that maps to a predefined border style from the design system. - `base`: A solid border line, suitable for most use cases. - `dashed`: A dashed border line, often used for drop zones or placeholder boundaries. - `dotted`: A dotted border line. - `none`: No border is rendered.

'base' | 'dashed' | 'dotted' | 'none'

CornerRadius

A keyword that maps to a predefined corner radius from the design system. - `base`: The default corner radius. - `small`: A subtle corner radius, smaller than `base`. - `large`: A pronounced corner radius, larger than `base`. - `fullyRounded`: Fully rounds the corners into a pill or circle shape. - `none`: No corner rounding; sharp square corners.

'base' | 'small' | 'large' | 'fullyRounded' | 'none' | CornerRadiusDeprecated

CornerRadiusDeprecated

'tight' | 'loose'

BorderWidth

A keyword that maps to a predefined border width from the design system. - `base`: The default border width. - `medium`: A medium border width, thicker than `base`. - `thick`: The thickest available border width.

'base' | 'medium' | 'thick'

Fit

Controls how an image fits within its frame when the image's intrinsic dimensions differ from the frame's dimensions. - `cover`: The image fills the entire frame while maintaining its aspect ratio. If the image is larger than the frame, it will be cropped. - `contain`: The image fits within the frame while maintaining its aspect ratio. The frame may have empty space if the aspect ratios differ. Learn more about the [object-fit](https://developer.mozilla.org/en-US/docs/Web/CSS/object-fit) property.

'cover' | 'contain'

Loading

Controls when the browser begins loading the image. - `eager`: Loads the image immediately, regardless of whether it’s visible in the viewport. - `lazy`: Defers loading until the image approaches the visible viewport, which can improve initial page performance.

'eager' | 'lazy'

MaybeConditionalStyle

A type that represents a value that can be a conditional style. We highly recommend using the `Style` helper which simplifies the creation of conditional styles.

T | ConditionalStyle<T, AcceptedConditions>

AtLeastOne

A utility type that requires at least one property from the given type to be present. Used to ensure that conditional style objects always specify at least one condition.

Partial<T> & U[keyof U]

ResolutionCondition

A condition that targets devices based on their pixel density.

resolution
The minimum device pixel ratio the condition must match.
```
Resolution
```

Resolution

The device pixel ratio used to serve resolution-appropriate images. A value of `1` targets standard displays, while higher values such as `2` or `3` target high-density (Retina) displays.

1 | 1.3 | 1.5 | 2 | 2.6 | 3 | 3.5 | 4

Anchor to LoadingLoading

Value	Description
`"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?