Migrate Thumbnail from Polaris React

Use s-thumbnail for a compact resource preview and preserve meaningful alternative text. Use s-image when the image is primary content rather than a thumbnail.

Anchor to Choose the destinationChoose the destination

Anchor to Map thumbnail propertiesMap thumbnail properties

The destination also provides small-100 and large-100 intermediate values. Choose among the documented scale based on the resource hierarchy, and use one consistent size within a table, list, or grid.

Anchor to Migrate the call siteMigrate the call site

1. Inventory every Thumbnail call site and record the content, state, events, and accessibility behavior it uses.

2. Open the linked Polaris web component reference and map only documented properties, slots, and events.

3. Move unsupported responsibilities into adjacent content or app state instead of passing old props through.

4. After verification, remove the Thumbnail import and any Polaris-only state, wrappers, or helpers that no longer have a caller.

Anchor to Preserve these behaviorsPreserve these behaviors

• Accessible names, semantics, and keyboard behavior.
• Visible content plus disabled, loading, selected, or error state that affects the task.
• Click, change, submit, and navigation behavior used by app logic.

Anchor to Test and remove Polaris ReactTest and remove Polaris React

Test every migrated Thumbnail state used by the app. For interactive destinations, verify keyboard operation, focus, and accessible naming. For content destinations, verify document structure and alternative text where applicable. Compare behavior rather than pixel-for-pixel styling.

Don't remove @shopify/polaris while another component still imports it. Once all call sites are migrated, remove the package and its provider-level setup, then run the app's full test suite.

Anchor to Migration exampleMigration example

export function ThumbnailMigrationExample() {
  return (
    <s-thumbnail
      src="https://cdn.shopify.com/static/images/polaris/thumbnail-wc_src.jpg"
      alt="White sneaker"
      size="large"
    />
  );
}

import {Thumbnail} from '@shopify/polaris';

export function ThumbnailMigrationExample() {
  return (
    <Thumbnail
      source="https://cdn.shopify.com/static/images/polaris/thumbnail-wc_src.jpg"
      alt="White sneaker"
      size="large"
    />
  );
}