---
title: Migrate to the Polaris product thumbnail component
description: >-
  Learn how to migrate the ProductThumbnail component to Polaris web components
  in checkout and customer account UI extensions.
source_url:
  html: >-
    https://shopify.dev/docs/apps/build/checkout/migrate-to-web-components/product-thumbnail
  md: >-
    https://shopify.dev/docs/apps/build/checkout/migrate-to-web-components/product-thumbnail.md
---

# Migrate to the Polaris product thumbnail component

The Polaris product thumbnail component renders a small image representing a product. It replaces the previous [`ProductThumbnail`](https://shopify.dev/docs/api/checkout-ui-extensions/2025-07/ui-components/media/productthumbnail) component and is available as [`<s-product-thumbnail>`](https://shopify.dev/docs/api/checkout-ui-extensions/latest/web-components/media/product-thumbnail) in API versions 2025-10 and newer.

***

## Updated properties

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

### accessibility​Label

The previous `ProductThumbnail` `accessibilityLabel` prop is now called [`alt`](https://shopify.dev/docs/api/checkout-ui-extensions/latest/web-components/media/product-thumbnail#properties-propertydetail-alt).

### badge

The previous `ProductThumbnail` `badge` prop is now called [`totalItems`](https://shopify.dev/docs/api/checkout-ui-extensions/latest/web-components/media/product-thumbnail#properties-propertydetail-totalitems).

### source

The previous `ProductThumbnail` `source` prop is now called [`src`](https://shopify.dev/docs/api/checkout-ui-extensions/latest/web-components/media/product-thumbnail#properties-propertydetail-src).

| Previous pattern | New pattern | Migration notes |
| - | - | - |
| `source="url"` | `src="url"` | Simple source renamed to `src`. |

## Migrating source to src

##### Latest (Preact)

```tsx
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>
  );
}
```

##### Pre-Polaris (2025-07)

```tsx
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`](https://shopify.dev/docs/api/checkout-ui-extensions/latest/web-components/media/product-thumbnail#properties-propertydetail-srcset) and [`sizes`](https://shopify.dev/docs/api/checkout-ui-extensions/latest/web-components/media/product-thumbnail#properties-propertydetail-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`.

## Migrating MaybeConditionalStyle source to srcSet

##### Latest (Preact)

```tsx
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>
  );
}
```

##### Pre-Polaris (2025-07)

```tsx
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"
    />
  );
}
```

### size

The `size` prop has a new option available:

| Previous value | New value | Migration notes |
| - | - | - |
| `'small'` | `'small'` or `'small-100'` | Both are supported. `'small'` maps to `'small-100'`. |
| `'base'` | `'base'` | No change needed. |

For more on the scale system, see [Scale](https://shopify.dev/docs/api/checkout-ui-extensions/latest/using-polaris-components#scale).

***

## New properties

The Polaris product thumbnail component introduces the following new properties:

| New prop | Type | Description |
| - | - | - |
| [`srcSet`](https://shopify.dev/docs/api/checkout-ui-extensions/latest/web-components/media/product-thumbnail#properties-propertydetail-srcset) | `string` | Defines multiple image sources for different resolutions or viewport sizes. |
| [`sizes`](https://shopify.dev/docs/api/checkout-ui-extensions/latest/web-components/media/product-thumbnail#properties-propertydetail-sizes) | `string` | Defines the sizes of the image for different viewport conditions. Used with `srcSet`. |

***