Migrate to the Polaris product thumbnail component

The Polaris product thumbnail component renders a small image representing a product. It replaces the previous ProductThumbnail component and is available as <s-product-thumbnail> in API versions 2025-10 and newer.

Anchor to Updated propertiesUpdated properties

The following properties are different in the Polaris product thumbnail component.

Anchor to accessibilityLabelaccessibilityLabel

The previous ProductThumbnail accessibilityLabel prop is now called alt.

Anchor to badgebadge

The previous ProductThumbnail badge prop is now called totalItems.

Anchor to sourcesource

The previous ProductThumbnail 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-product-thumbnail
      src="https://example.com/product.jpg"
      alt="Blue t-shirt"
      totalItems={2}
      size="base"
    ></s-product-thumbnail>
  );
}

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

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

function Extension() {
  return (
    <ProductThumbnail
      source="https://example.com/product.jpg"
      accessibilityLabel="Blue t-shirt"
      badge={2}
      size="base"
    />
  );
}

If you previously used a MaybeConditionalStyle value with source to swap images at different viewport sizes, use srcSet and sizes instead. Provide each candidate image with a width descriptor (Nw) in srcSet and tell the browser what rendered size to expect at each breakpoint with sizes — the browser then picks the smallest source that satisfies the rendered size and pixel density.

For density switching only (same rendered size, different DPR), use the 1x/2x form in srcSet and omit sizes.

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

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

function Extension() {
  return (
    <s-product-thumbnail
      src="https://example.com/product-small.jpg"
      srcSet="https://example.com/product-small.jpg 100w, https://example.com/product-large.jpg 200w"
      sizes="(min-width: 600px) 200px, 100px"
      alt="Blue t-shirt"
    ></s-product-thumbnail>
  );
}

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

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

function Extension() {
  return (
    <ProductThumbnail
      source={Style.default('https://example.com/product-small.jpg')
        .when({viewportInlineSize: {min: 'small'}}, 'https://example.com/product-large.jpg')}
      accessibilityLabel="Blue t-shirt"
    />
  );
}

Anchor to sizesize

The size prop has a new option available:

For more on the scale system, see Scale.

Anchor to New propertiesNew properties

The Polaris product thumbnail component introduces the following new properties: