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

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. For profile images, use Avatar.

Support
Targets (25)

Supported targets

Anchor to PropertiesProperties

Configure the following properties on the Image component.

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.

Anchor to ExamplesExamples

Anchor to Display an imageDisplay 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.

Display an image

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

export default reactExtension(
'customer-account.page.render',
() => <Extension />,
);

function Extension() {
return (
<Image source="https://cdn.shopify.com/YOUR_IMAGE_HERE" />
);
}
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);
});

Anchor to Display a product imageDisplay 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

import {
reactExtension,
Image,
Text,
BlockStack,
InlineStack,
} from '@shopify/ui-extensions-react/customer-account';

export default reactExtension(
'customer-account.page.render',
() => <Extension />,
);

function Extension() {
return (
<InlineStack spacing="base">
<Image
source="https://cdn.shopify.com/static/sample-product/House-Plant1.png"
accessibilityLabel="Indoor plant in a gray pot"
aspectRatio={1}
/>
<BlockStack spacing="small">
<Text emphasis="bold">Indoor Plant</Text>
<Text appearance="subdued">Qty: 2</Text>
<Text appearance="success">Delivered</Text>
</BlockStack>
</InlineStack>
);
}
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);
});

Anchor to Set an aspect ratioSet 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

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

export default reactExtension(
'customer-account.page.render',
() => <Extension />,
);

function Extension() {
return (
<BlockStack spacing="base">
<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"
/>
<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"
/>
</BlockStack>
);
}
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);
});

Anchor to Mark an image as decorativeMark 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

import {
reactExtension,
Image,
Text,
Heading,
BlockStack,
} from '@shopify/ui-extensions-react/customer-account';

export default reactExtension(
'customer-account.page.render',
() => <Extension />,
);

function Extension() {
return (
<BlockStack spacing="base">
<Image
source="https://cdn.shopify.com/static/sample-product/House-Plant1.png"
accessibilityLabel=""
accessibilityRole="decorative"
/>
<Heading>Your order is on its way</Heading>
<Text appearance="subdued">
Estimated delivery: April 15, 2026
</Text>
</BlockStack>
);
}
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);
});

Anchor to Best practicesBest 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 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.

Anchor to LimitationsLimitations

  • 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 for loading placeholders.
Was this page helpful?