--- title: Image description: >- 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. 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 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 aspect ratio control, object fit, and loading states for progressive enhancement. For small product preview images, use [ProductThumbnail](https://shopify.dev/docs/api/customer-account-ui-extensions/2025-07/ui-components/media-and-visuals/productthumbnail). For profile images, use [Avatar](https://shopify.dev/docs/api/customer-account-ui-extensions/2025-07/ui-components/media-and-visuals/avatar). ### Support Targets (25) ### Supported targets * Customer​Account::Kitchen​Sink * [customer-account.​footer.​render-after](https://shopify.dev/docs/api/customer-account-ui-extensions/2025-07/targets/footer#footer-render-after-) * [customer-account.​order-index.​announcement.​render](https://shopify.dev/docs/api/customer-account-ui-extensions/2025-07/targets/order-index#order-index-targets) * [customer-account.​order-index.​block.​render](https://shopify.dev/docs/api/customer-account-ui-extensions/2025-07/targets/order-index#order-index-block-) * [customer-account.​order-status.​announcement.​render](https://shopify.dev/docs/api/customer-account-ui-extensions/2025-07/targets/order-status#order-status-announcement-) * [customer-account.​order-status.​block.​render](https://shopify.dev/docs/api/customer-account-ui-extensions/2025-07/targets/order-status#order-status-block-) * [customer-account.​order-status.​cart-line-item.​render-after](https://shopify.dev/docs/api/customer-account-ui-extensions/2025-07/targets/order-status#cart-line-item-render-after-) * [customer-account.​order-status.​cart-line-list.​render-after](https://shopify.dev/docs/api/customer-account-ui-extensions/2025-07/targets/order-status#cart-line-list-render-after-) * [customer-account.​order-status.​customer-information.​render-after](https://shopify.dev/docs/api/customer-account-ui-extensions/2025-07/targets/order-status#customer-information-render-after-) * [customer-account.​order-status.​fulfillment-details.​render-after](https://shopify.dev/docs/api/customer-account-ui-extensions/2025-07/targets/fulfillment-status#fulfillment-status-targets) * [customer-account.​order-status.​payment-details.​render-after](https://shopify.dev/docs/api/customer-account-ui-extensions/2025-07/targets/payments-and-returns#payments-and-returns-targets) * [customer-account.​order-status.​return-details.​render-after](https://shopify.dev/docs/api/customer-account-ui-extensions/2025-07/targets/payments-and-returns#return-details-render-after-) * [customer-account.​order-status.​unfulfilled-items.​render-after](https://shopify.dev/docs/api/customer-account-ui-extensions/2025-07/targets/fulfillment-status#unfulfilled-items-render-after-) * [customer-account.​order.​action.​menu-item.​render](https://shopify.dev/docs/api/customer-account-ui-extensions/2025-07/targets/order-actions#order-action-menu-item-) * [customer-account.​order.​action.​render](https://shopify.dev/docs/api/customer-account-ui-extensions/2025-07/targets/order-actions#order-action-) * [customer-account.​order.​page.​render](https://shopify.dev/docs/api/customer-account-ui-extensions/2025-07/targets/full-page#order-specific-full-page-) * [customer-account.​page.​render](https://shopify.dev/docs/api/customer-account-ui-extensions/2025-07/targets/full-page#customer-account-full-page-) * [customer-account.​profile.​addresses.​render-after](https://shopify.dev/docs/api/customer-account-ui-extensions/2025-07/targets/profile-page-default#profile-page-default-targets-) * [customer-account.​profile.​announcement.​render](https://shopify.dev/docs/api/customer-account-ui-extensions/2025-07/targets/profile-page-default#announcement-) * [customer-account.​profile.​block.​render](https://shopify.dev/docs/api/customer-account-ui-extensions/2025-07/targets/profile-page-default#profile-block-) * [customer-account.​profile.​company-details.​render-after](https://shopify.dev/docs/api/customer-account-ui-extensions/2025-07/targets/profile-page-b2b#profile-page-b2b-targets-) * [customer-account.​profile.​company-location-addresses.​render-after](https://shopify.dev/docs/api/customer-account-ui-extensions/2025-07/targets/profile-page-b2b#company-location-addresses-render-after-) * [customer-account.​profile.​company-location-payment.​render-after](https://shopify.dev/docs/api/customer-account-ui-extensions/2025-07/targets/profile-page-b2b#company-location-payment-render-after-) * [customer-account.​profile.​company-location-staff.​render-after](https://shopify.dev/docs/api/customer-account-ui-extensions/2025-07/targets/profile-page-b2b#company-location-staff-render-after-) * customer-account.​profile.​payment.​render-after #### Use cases * **Product visuals**: Display product images in order details, wishlists, or recommendations. * **Branding**: Show app logos or brand imagery in account extensions. * **Visual guides**: Provide visual instructions or examples for complex configurations. * **Content imagery**: Display promotional banners, feature announcements, or instructional screenshots. * **Responsive sizing**: Use [StyleHelper](https://shopify.dev/docs/api/customer-account-ui-extensions/2025-07/ui-components/layout-and-structure/stylehelper) to adjust image dimensions at different viewport sizes. *** ## Properties Configure the following properties on the Image component. * **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** **'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). * **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. 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. * **borderWidth** **MaybeResponsiveConditionalStyle< MaybeShorthandProperty\ >** 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. * **cornerRadius** **MaybeResponsiveConditionalStyle< MaybeShorthandProperty\ >** 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. * **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. Use this to target the component in scripts or stylesheets, or to distinguish it from other instances of the same 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** 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. ```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 ### Display an image Embed an image from a URL. This example renders a basic image component with a remote source. ## Display an image ![A basic image component displaying a product photo.](https://shopify.dev/assets/assets/images/api/checkout-extensions/post-purchase/components/image-BTyMz2U6.png) ## Display an 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); }); ``` ### Display a product image Display a product image alongside product details in a layout. This example demonstrates how to control image sizing with `aspectRatio` and pair the image with product details using an `InlineStack`. ## Display a product image ##### React ```tsx import { reactExtension, Image, Text, BlockStack, InlineStack, } from '@shopify/ui-extensions-react/customer-account'; export default reactExtension( 'customer-account.page.render', () => , ); function Extension() { return ( Indoor Plant Qty: 2 Delivered ); } ``` ##### JS ```js import {extension, Image, Text, BlockStack, InlineStack} from '@shopify/ui-extensions/customer-account'; export default extension('customer-account.page.render', (root) => { const image = root.createComponent(Image, { source: 'https://cdn.shopify.com/static/sample-product/House-Plant1.png', accessibilityLabel: 'Indoor plant in a gray pot', aspectRatio: 1, }); const name = root.createComponent(Text, {emphasis: 'bold'}, 'Indoor Plant'); const qty = root.createComponent(Text, {appearance: 'subdued'}, 'Qty: 2'); const status = root.createComponent(Text, {appearance: 'success'}, 'Delivered'); const details = root.createComponent(BlockStack, {spacing: 'small'}); details.append(name); details.append(qty); details.append(status); const row = root.createComponent(InlineStack, {spacing: 'base'}); row.append(image); row.append(details); root.append(row); }); ``` ### Set an aspect ratio Compare different aspect ratios on the same image. This example stacks a 1:1 square crop above a 16:9 widescreen crop, both using `fit="cover"` to fill their containers. ## Set an aspect ratio ##### React ```tsx import { reactExtension, Image, BlockStack, } from '@shopify/ui-extensions-react/customer-account'; export default reactExtension( 'customer-account.page.render', () => , ); function Extension() { return ( ); } ``` ##### JS ```js import {extension, Image, BlockStack} from '@shopify/ui-extensions/customer-account'; export default extension('customer-account.page.render', (root) => { const square = root.createComponent(Image, { source: 'https://cdn.shopify.com/static/sample-product/House-Plant1.png', accessibilityLabel: 'Indoor plant in a gray pot, square crop', aspectRatio: 1, fit: 'cover', }); const wide = root.createComponent(Image, { source: 'https://cdn.shopify.com/static/sample-product/House-Plant1.png', accessibilityLabel: 'Indoor plant in a gray pot, widescreen crop', aspectRatio: 16 / 9, fit: 'cover', }); const stack = root.createComponent(BlockStack, {spacing: 'base'}); stack.append(square); stack.append(wide); root.append(stack); }); ``` ### Mark an image as decorative Hide images from screen readers when purely decorative. This example presents an image with an empty `accessibilityLabel` and `accessibilityRole="decorative"` so assistive technologies skip it. ## Mark an image as decorative ##### React ```tsx import { reactExtension, Image, Text, Heading, BlockStack, } from '@shopify/ui-extensions-react/customer-account'; export default reactExtension( 'customer-account.page.render', () => , ); function Extension() { return ( Your order is on its way Estimated delivery: April 15, 2026 ); } ``` ##### JS ```js import {extension, Image, Text, Heading, BlockStack} from '@shopify/ui-extensions/customer-account'; export default extension('customer-account.page.render', (root) => { const image = root.createComponent(Image, { source: 'https://cdn.shopify.com/static/sample-product/House-Plant1.png', accessibilityLabel: '', accessibilityRole: 'decorative', }); const heading = root.createComponent(Heading, {}, 'Your order is on its way'); const delivery = root.createComponent(Text, {appearance: 'subdued'}, 'Estimated delivery: April 15, 2026'); const stack = root.createComponent(BlockStack, {spacing: 'base'}); stack.append(image); stack.append(heading); stack.append(delivery); root.append(stack); }); ``` *** ## Best practices * **Always provide descriptive alt text**: Write alt text that describes what's in the image, not what the image is for. Use "Blue cotton t-shirt with crew neck" instead of "Product image." For decorative images that don't add information, use an empty `accessibilityLabel` with `accessibilityRole="decorative"`. * **Use images for meaningful content, not decoration**: Display product photos, diagrams, charts, or instructional screenshots. For icons or decorative elements, use the [Icon](https://shopify.dev/docs/api/customer-account-ui-extensions/2025-07/ui-components/media-and-visuals/icon) component instead. * **Ensure images are accessible and performant**: Use appropriate image formats (WebP for photos, PNG for graphics with transparency). Ensure images load from reliable sources with proper CORS configuration if cross-origin. * **Consider the image's purpose and context**: Use images to help customers understand products, visualize data, or follow instructions. Every image should serve a clear purpose in your interface. *** ## Limitations * Images can be loaded from remote URLs. Cross-origin images require proper CORS headers from the image host. * The component displays images at their intrinsic aspect ratio unless overridden with `aspectRatio`. Use `fit` (`"cover"` or `"contain"`) to control how the image resizes within its container. * The component provides a basic placeholder while images load but doesn't include built-in loading skeletons. Use [SkeletonImage](https://shopify.dev/docs/api/customer-account-ui-extensions/2025-07/ui-components/media-and-visuals/skeletonimage) for loading placeholders. ***