--- 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: 2026-04 api_name: customer-account-ui-extensions source_url: html: >- https://shopify.dev/docs/api/customer-account-ui-extensions/latest/web-components/media-and-visuals/image md: >- https://shopify.dev/docs/api/customer-account-ui-extensions/latest/web-components/media-and-visuals/image.md --- # 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 product preview images, use [product thumbnail](https://shopify.dev/docs/api/customer-account-ui-extensions/latest/web-components/media-and-visuals/product-thumbnail). For profile images, use [avatar](https://shopify.dev/docs/api/customer-account-ui-extensions/latest/web-components/media-and-visuals/avatar). Images can load from remote URLs or local file resources. Cross-origin images require proper CORS headers from the image host. A basic placeholder shows while loading — there's no built-in loading skeleton or progressive loading. ### Support Targets (24) ### Supported targets * [customer-account.​footer.​render-after](https://shopify.dev/docs/api/customer-account-ui-extensions/2026-04/targets/footer#footer-render-after-) * [customer-account.​order-index.​announcement.​render](https://shopify.dev/docs/api/customer-account-ui-extensions/2026-04/targets/order-actions#order-index-announcement-) * [customer-account.​order-index.​block.​render](https://shopify.dev/docs/api/customer-account-ui-extensions/2026-04/targets/order-actions#order-index-block-) * [customer-account.​order-status.​announcement.​render](https://shopify.dev/docs/api/customer-account-ui-extensions/2026-04/targets/order-status#order-status-announcement-) * [customer-account.​order-status.​block.​render](https://shopify.dev/docs/api/customer-account-ui-extensions/2026-04/targets/order-status#order-status-block-) * [customer-account.​order-status.​cart-line-item.​render-after](https://shopify.dev/docs/api/customer-account-ui-extensions/2026-04/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/2026-04/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/2026-04/targets/order-status#customer-information-render-after-) * [customer-account.​order-status.​fulfillment-details.​render-after](https://shopify.dev/docs/api/customer-account-ui-extensions/2026-04/targets/fulfillment-status#fulfillment-status-targets) * [customer-account.​order-status.​payment-details.​render-after](https://shopify.dev/docs/api/customer-account-ui-extensions/2026-04/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/2026-04/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/2026-04/targets/fulfillment-status#unfulfilled-items-render-after-) * [customer-account.​order.​action.​menu-item.​render](https://shopify.dev/docs/api/customer-account-ui-extensions/2026-04/targets/order-actions#order-action-menu-item-) * [customer-account.​order.​action.​render](https://shopify.dev/docs/api/customer-account-ui-extensions/2026-04/targets/order-actions#order-action-) * [customer-account.​order.​page.​render](https://shopify.dev/docs/api/customer-account-ui-extensions/2026-04/targets/full-page#order-specific-full-page-) * [customer-account.​page.​render](https://shopify.dev/docs/api/customer-account-ui-extensions/2026-04/targets/full-page#customer-account-full-page-) * [customer-account.​profile.​addresses.​render-after](https://shopify.dev/docs/api/customer-account-ui-extensions/2026-04/targets/profile-page-default#profile-page-default-targets-) * [customer-account.​profile.​announcement.​render](https://shopify.dev/docs/api/customer-account-ui-extensions/2026-04/targets/profile-page-default#profile-announcement-) * [customer-account.​profile.​block.​render](https://shopify.dev/docs/api/customer-account-ui-extensions/2026-04/targets/profile-page-default#profile-block-) * [customer-account.​profile.​company-details.​render-after](https://shopify.dev/docs/api/customer-account-ui-extensions/2026-04/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/2026-04/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/2026-04/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/2026-04/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. *** ## Properties Configure the following properties on the image component. * **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. * **alt** **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](https://www.shopify.com/ca/blog/image-alt-text#4) and the [alt attribute](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/img#alt). * **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](https://developer.mozilla.org/en-US/docs/Web/CSS/aspect-ratio). * **border** **BorderShorthand** **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. * **borderRadius** **MaybeAllValuesShorthandProperty\>** **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](https://developer.mozilla.org/en-US/docs/Web/CSS/Shorthand_properties#edges_of_a_box) to control individual corners. * **borderStyle** **MaybeAllValuesShorthandProperty\ | ""** **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](https://developer.mozilla.org/en-US/docs/Web/CSS/Shorthand_properties#edges_of_a_box) 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 * **borderWidth** **MaybeAllValuesShorthandProperty\ | ''** **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](https://developer.mozilla.org/en-US/docs/Web/CSS/Shorthand_properties#edges_of_a_box) to control individual sides. When set, this overrides the width value specified in the `border` shorthand. * **id** **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. * **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](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/img#width). * **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](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/img#loading). * **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](https://developer.mozilla.org/en-US/docs/Web/CSS/object-fit). * `'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. * **sizes** **string** A set of media conditions and their corresponding sizes. Learn more about the [sizes attribute](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/img#sizes). * **src** **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](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/img#src). * **srcSet** **string** A set of image sources and their width or pixel density descriptors. Learn more about the [srcset attribute](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/img#srcset). This overrides the `src` property. ### BorderShorthand A shorthand string for specifying border properties. Accepts a size alone (\`'base'\`), size with color (\`'base base'\`), or size with color and style (\`'base base dashed'\`). Omitted values use their defaults. ```ts ReducedBorderSizeKeyword | `${ReducedBorderSizeKeyword} ${ReducedColorKeyword}` | `${ReducedBorderSizeKeyword} ${ReducedColorKeyword} ${BorderStyleKeyword}` ``` ### ReducedBorderSizeKeyword The subset of border size values available for this component. - \`base\`: Standard border width. - \`large\`: Thick border for strong emphasis. - \`large-100\`: Extra thick border for maximum prominence. - \`large-200\`: The thickest available border. - \`none\`: No border. ```ts 'base' | 'large' | 'large-100' | 'large-200' | 'none' ``` ### ReducedColorKeyword The subset of border color values available for this component. - \`base\`: The standard border color for most contexts. ```ts 'base' ``` ### BorderStyleKeyword The visual style of a border. Learn more about \[border-style]\(https://developer.mozilla.org/en-US/docs/Web/CSS/border-style). - \`none\`: No border is rendered. - \`solid\`: A single continuous line. - \`dashed\`: A series of short dashes. - \`dotted\`: A series of round dots. - \`auto\`: The border style is determined automatically based on the surface's design system. ```ts "none" | "solid" | "dashed" | "dotted" | "auto" ``` ### MaybeAllValuesShorthandProperty Represents CSS shorthand properties that accept one to four values, following the \[CSS shorthand syntax]\(https://developer.mozilla.org/en-US/docs/Web/CSS/Shorthand\_properties#edges\_of\_a\_box). Supports specifying values for all four sides: top, right, bottom, and left. - \`T\`: Single value that applies to all four sides. - \`${T} ${T}\`: Two values for block axis (top/bottom) and inline axis (left/right). - \`${T} ${T} ${T}\`: Three values for block-start (top), inline axis (left/right), and block-end (bottom). - \`${T} ${T} ${T} ${T}\`: Four values for block-start (top), inline-end (right), block-end (bottom), and inline-start (left). ```ts T | `${T} ${T}` | `${T} ${T} ${T}` | `${T} ${T} ${T} ${T}` ``` ### ImageProps The properties for the image component when it's used in JSX. * accessibilityRole 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. ```ts 'img' | 'none' | 'presentation' ``` * alt 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]\(https://www\.shopify.com/ca/blog/image-alt-text#4) and the \[alt attribute]\(https://developer.mozilla.org/en-US/docs/Web/HTML/Element/img#alt). ```ts string ``` * aspectRatio 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]\(https://developer.mozilla.org/en-US/docs/Web/CSS/aspect-ratio). ```ts `${number}${optionalSpace}/${optionalSpace}${number}` | `${number}` ``` * border 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. ```ts BorderShorthand ``` * borderRadius 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]\(https://developer.mozilla.org/en-US/docs/Web/CSS/Shorthand\_properties#edges\_of\_a\_box) to control individual corners. ```ts MaybeAllValuesShorthandProperty> ``` * borderStyle 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]\(https://developer.mozilla.org/en-US/docs/Web/CSS/Shorthand\_properties#edges\_of\_a\_box) 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 ```ts MaybeAllValuesShorthandProperty | "" ``` * borderWidth 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]\(https://developer.mozilla.org/en-US/docs/Web/CSS/Shorthand\_properties#edges\_of\_a\_box) to control individual sides. When set, this overrides the width value specified in the \`border\` shorthand. ```ts MaybeAllValuesShorthandProperty | '' ``` * id 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. ```ts string ``` * inlineSize 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]\(https://developer.mozilla.org/en-US/docs/Web/HTML/Element/img#width). ```ts 'fill' | 'auto' ``` * loading 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]\(https://developer.mozilla.org/en-US/docs/Web/HTML/Element/img#loading). ```ts 'eager' | 'lazy' ``` * objectFit 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]\(https://developer.mozilla.org/en-US/docs/Web/CSS/object-fit). - \`'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. ```ts 'contain' | 'cover' ``` * sizes A set of media conditions and their corresponding sizes. Learn more about the \[sizes attribute]\(https://developer.mozilla.org/en-US/docs/Web/HTML/Element/img#sizes). ```ts string ``` * src 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]\(https://developer.mozilla.org/en-US/docs/Web/HTML/Element/img#src). ```ts string ``` * srcSet A set of image sources and their width or pixel density descriptors. Learn more about the \[srcset attribute]\(https://developer.mozilla.org/en-US/docs/Web/HTML/Element/img#srcset). This overrides the \`src\` property. ```ts string ``` *** ## Examples ### Display a product image Display a product image with rounded corners. This example demonstrates how to control image sizing with `objectFit` and `inlineSize`, and round corners with `borderRadius`. ## Display a product image ![A rounded product photo of an indoor plant displayed as a standalone image element.](https://shopify.dev/assets/assets/images/templated-apis-screenshots/checkout-ui-extensions/2025-10/image-default-Da5YNYF4.png) ## html ```html ``` ### 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 `objectFit="cover"` to fill their containers. ## html ```html ``` ### Use responsive images Set up responsive image sources using `srcSet` and `sizes`. This example demonstrates how to configure the browser to select appropriate image sources based on viewport width. ## html ```html ``` ### Add border styling Add visual emphasis with border styling. This example displays an image with border width, color, and rounded corners. ## html ```html ``` ### Mark as decorative Hide images from screen readers when purely decorative. This example presents an image with empty `alt` text and `presentation` role for accessibility. ## html ```html ``` ### Use in a grid layout Build a product image gallery with consistent sizing using [grid](https://shopify.dev/docs/api/customer-account-ui-extensions/latest/web-components/layout-and-structure/grid). This example arranges three product photos in a row, each constrained to a square with rounded corners so they line up evenly. ## html ```html ``` *** ## 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 alt attribute. * **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/latest/web-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, SVG for logos). 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. ***