--- title: Image description: 'Image is used for large format, responsive images.' api_version: 2025-07 api_name: customer-account-ui-extensions source_url: html: >- https://shopify.dev/docs/api/customer-account-ui-extensions/2025-07/ui-components/media-and-visuals/image md: >- https://shopify.dev/docs/api/customer-account-ui-extensions/2025-07/ui-components/media-and-visuals/image.md --- Migrate to Polaris Version 2025-07 is the last API version to support React-based UI components. Later versions use [web components](https://shopify.dev/docs/api/customer-account-ui-extensions/latest/polaris-web-components), native UI elements with built-in accessibility, better performance, and consistent styling with [Shopify's design system](https://shopify.dev/docs/apps/design). Check out the [migration guide](https://shopify.dev/docs/apps/build/customer-accounts/migrate-to-web-components) to upgrade your extension. # Image Image is used for large format, responsive images. ### Support Targets (25) ### Supported targets * Customer​Account::Kitchen​Sink * customer-account.​footer.​render-after * customer-account.​order-index.​announcement.​render * customer-account.​order-index.​block.​render * customer-account.​order-status.​announcement.​render * customer-account.​order-status.​block.​render * customer-account.​order-status.​cart-line-item.​render-after * customer-account.​order-status.​cart-line-list.​render-after * customer-account.​order-status.​customer-information.​render-after * customer-account.​order-status.​fulfillment-details.​render-after * customer-account.​order-status.​payment-details.​render-after * customer-account.​order-status.​return-details.​render-after * customer-account.​order-status.​unfulfilled-items.​render-after * customer-account.​order.​action.​menu-item.​render * customer-account.​order.​action.​render * customer-account.​order.​page.​render * customer-account.​page.​render * customer-account.​profile.​addresses.​render-after * customer-account.​profile.​announcement.​render * customer-account.​profile.​block.​render * customer-account.​profile.​company-details.​render-after * customer-account.​profile.​company-location-addresses.​render-after * customer-account.​profile.​company-location-payment.​render-after * customer-account.​profile.​company-location-staff.​render-after * customer-account.​profile.​payment.​render-after ## ImageProps * **source** **Required< MaybeConditionalStyle< string, AtLeastOne\ > >** **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. * **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](https://ux.shopify.com/considerations-when-writing-alt-text-a9c1985a8204). * **accessibilityRole** **Extract\** 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). * **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. * **border** **MaybeResponsiveConditionalStyle\>** 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` * **borderWidth** **MaybeResponsiveConditionalStyle< MaybeShorthandProperty\ >** 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` * **cornerRadius** **MaybeResponsiveConditionalStyle< MaybeShorthandProperty\ >** 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. * **fit** **MaybeResponsiveConditionalStyle\** The fit of the image within its frame. Use when the image is not displayed at its intrinsic size to maintain the aspect ratio. * **id** **string** A unique identifier for the component. * **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. * **borderRadius** **MaybeResponsiveConditionalStyle< MaybeShorthandProperty\ >** **deprecated** **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. ### AccessibilityRole The set of accessibility roles that can be applied to components to convey semantic meaning to assistive technologies. Each role maps to a corresponding HTML element or ARIA role in web-based hosts. - \`main\`: The primary content of the page. - \`header\`: A header section of the page. - \`footer\`: A section for copyright information, navigation links, and privacy statements. - \`section\`: A generic section; should have a heading or accessible label. - \`complementary\`: A supporting section related to the main content. - \`navigation\`: A major group of navigation links. - \`orderedList\`: A list of ordered items. - \`listItem\`: An item inside a list. - \`unorderedList\`: A list of unordered items. - \`separator\`: A divider separating sections of content. - \`status\`: A live region with advisory information that isn't urgent enough to be an alert. - \`alert\`: Important, usually time-sensitive information. - \`decorative\`: Marks the element as purely visual; assistive technologies skip it. - \`presentation\`: Strips semantic meaning but leaves visual styling intact. ```ts 'main' | 'header' | 'footer' | 'section' | 'complementary' | 'navigation' | 'orderedList' | 'listItem' | 'unorderedList' | 'separator' | 'status' | 'alert' | 'decorative' | 'presentation' ``` ### 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. ```ts T | ConditionalStyle ``` ### 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. ```ts ConditionalValue[] ``` * default The default value applied when none of the conditional values specified in \`conditionals\` are met. ```ts 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. ```ts AcceptedConditions ``` * value The value that will be applied if the conditions are met. ```ts 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. ```ts { 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. ```ts T | ShorthandProperty ``` ### 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. ```ts [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. ```ts '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. ```ts 'base' | 'small' | 'large' | 'fullyRounded' | 'none' | CornerRadiusDeprecated ``` ### CornerRadiusDeprecated ```ts '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. ```ts '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. ```ts '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. ```ts '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. ```ts T | ConditionalStyle ``` ### 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. ```ts Partial & U[keyof U] ``` ### ResolutionCondition A condition that targets devices based on their pixel density. * resolution The minimum device pixel ratio the condition must match. ```ts 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. ```ts 1 | 1.3 | 1.5 | 2 | 2.6 | 3 | 3.5 | 4 ``` Examples ## Preview ![](https://cdn.shopify.com/shopifycloud/shopify-dev/development/assets/assets/images/api/checkout-extensions/post-purchase/components/image-BTyMz2U6.png) ### Examples * #### Basic Image ##### React ```tsx import { reactExtension, Image, } from '@shopify/ui-extensions-react/customer-account'; export default reactExtension( 'customer-account.page.render', () => , ); function Extension() { return ( ); } ``` ##### JS ```js import {extension, Image} from '@shopify/ui-extensions/customer-account'; export default extension('customer-account.page.render', (root) => { const image = root.createComponent(Image, { source: 'https://cdn.shopify.com/YOUR_IMAGE_HERE', }); root.appendChild(image); }); ``` ## Loading | 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. |