Migrate to the Polaris image component

The Polaris image component renders images with built-in responsive behavior and accessibility support. It replaces the previous Image component and is available as <s-image> in API versions 2025-10 and newer.

Anchor to Updated propertiesUpdated properties

The following properties are different in the Polaris image component.

Anchor to sourcesource

The previous Image source prop is now called src.

import '@shopify/ui-extensions/preact';
import {render} from 'preact';

export default function extension() {
  render(<Extension />, document.body);
}

function Extension() {
  return (
    <s-image
      src="https://example.com/product.jpg"
      alt="Product image"
    />
  );
}

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

export default reactExtension(
  'purchase.checkout.block.render',
  () => <Extension />,
);

function Extension() {
  return (
    <Image
      source="https://example.com/product.jpg"
      accessibilityDescription="Product image"
    />
  );
}

Anchor to accessibilityDescriptionaccessibilityDescription

The previous Image accessibilityDescription prop is now called alt.

Anchor to cornerRadiuscornerRadius

The previous Image cornerRadius prop is now called borderRadius. Most token values carry over (none, small, base, large), but a few things changed:

Anchor to fitfit

The previous Image fit prop is now called objectFit.

Anchor to accessibilityRoleaccessibilityRole

The accessibilityRole value for decorative images has changed to align with the standard ARIA role. The intent is the same — the image carries no semantic meaning and assistive technologies should ignore it — but the value uses the web-standard name.

import '@shopify/ui-extensions/preact';
import {render} from 'preact';

export default function extension() {
  render(<Extension />, document.body);
}

function Extension() {
  return (
    <s-image
      src="https://example.com/decoration.jpg"
      alt=""
      accessibilityRole="presentation"
    />
  );
}

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

export default reactExtension(
  'purchase.checkout.block.render',
  () => <Extension />,
);

function Extension() {
  return (
    <Image
      source="https://example.com/decoration.jpg"
      accessibilityDescription=""
      accessibilityRole="decorative"
    />
  );
}

Anchor to aspectRatioaspectRatio

The aspectRatio prop now accepts string values instead of numbers. The string can be a single number (for example, "1.5") or a CSS-style ratio (for example, "16/9") — you don't need to pre-calculate the decimal. The default is "1/1".

import '@shopify/ui-extensions/preact';
import {render} from 'preact';

export default function extension() {
  render(<Extension />, document.body);
}

function Extension() {
  return (
    <s-image
      src="https://example.com/product.jpg"
      alt="Product image"
      aspectRatio="1.5"
    />
  );
}

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

export default reactExtension(
  'purchase.checkout.block.render',
  () => <Extension />,
);

function Extension() {
  return (
    <Image
      source="https://example.com/product.jpg"
      accessibilityDescription="Product image"
      aspectRatio={1.5}
    />
  );
}

Anchor to source with responsive conditionssource with responsive conditions

The previous pattern of passing an object with resolution or viewportInlineSize conditions to source is now handled with standard srcSet and sizes attributes.

srcSet accepts both width descriptors (for example, 400w) and pixel-density descriptors (for example, 2x). Width descriptors with a matching sizes attribute are the more common choice for viewport-responsive images.

import '@shopify/ui-extensions/preact';
import {render} from 'preact';

export default function extension() {
  render(<Extension />, document.body);
}

function Extension() {
  return (
    <s-image
      src="https://example.com/product-800.jpg"
      srcSet="https://example.com/product-400.jpg 400w, https://example.com/product-800.jpg 800w, https://example.com/product-1200.jpg 1200w"
      sizes="(min-width: 900px) 1200px, 100vw"
      alt="Product image"
    />
  );
}

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

export default reactExtension(
  'purchase.checkout.block.render',
  () => <Extension />,
);

function Extension() {
  return (
    <Image
      source={{
        default: 'https://example.com/product-800.jpg',
        viewportInlineSize: {
          small: 'https://example.com/product-400.jpg',
          large: 'https://example.com/product-1200.jpg',
        },
      }}
      accessibilityDescription="Product image"
    />
  );
}

For pixel-density-only responsiveness, use the 1x/2x form instead: srcSet="product.jpg 1x, product@2x.jpg 2x" (no sizes attribute needed).

Anchor to New propertiesNew properties

The Polaris image component introduces the following new properties: