Choose a version:

Thumbnail

The thumbnail component displays small preview images representing content, products, or media items. Use thumbnail to provide visual identification in lists, tables, or cards where space is constrained and quick recognition is important.

Thumbnails support multiple sizes, alt text for accessibility, and fallback states for missing images. For full-size images, use image. For user profile images, use avatar.

Support

Targets (46)

Supported targets

Anchor to PropertiesProperties

Configure the following properties on the thumbnail component.

Anchor to src src string required: The image source (either a remote URL or a local file resource).

When the image is loading or no src is provided, a placeholder is rendered.
Anchor to alt alt string Default: `` required: Alternative text that describes the image for accessibility.

Provides a text description of the image for users with assistive technology and serves as a fallback when the image fails to load. A well-written description enables people with visual impairments to understand non-text content.

When a screen reader encounters an image, it reads this description aloud. When an image fails to load, this text displays on screen, helping all users understand what content was intended.

Learn more about writing effective alt text and the alt attribute.
Anchor to size size "small" | "small-200" | "small-100" | "base" | "large" | "large-100" Default: 'base' required: The size of the product thumbnail image.

small-200: Smallest thumbnail size, ideal for compact product lists or tables.

small-100: Very small thumbnail, suitable for dense layouts.

small: Small thumbnail for space-constrained contexts.

base: Default size that balances visibility and space efficiency.

large: Larger thumbnail for featured products or detailed views.

large-100: Extra large thumbnail for prominent product display.

Anchor to EventsEvents

The thumbnail component provides event callbacks for handling user interactions. Learn more about handling events.

Anchor to error error OnErrorEventHandler required: A callback fired when the thumbnail image fails to load.

Learn more about the error event.
Anchor to load load <typeof tagName> | null required: A callback fired when the thumbnail image successfully loads.

Learn more about the load event.

CallbackEventListener

A function that handles events from UI components. This type represents an event listener callback that receives a `CallbackEvent` with a strongly-typed `currentTarget`. Use this for component event handlers like `click`, `focus`, `blur`, and other DOM events.

(EventListener & {
      (event: CallbackEvent<T>): void;
    }) | null

CallbackEvent

An event object with a strongly-typed `currentTarget` property that references the specific HTML element that triggered the event. This type extends the standard DOM `Event` interface and ensures type safety when accessing the element that fired the event.

Event & {
  currentTarget: HTMLElementTagNameMap[T];
}

Anchor to ExamplesExamples

Anchor to Display a thumbnailDisplay a thumbnail

Display small preview images for products or items. This example presents a basic thumbnail with source URL and alt text for accessibility.

Preview

html

<s-thumbnail

alt="Image of white sneakers"

src="https://cdn.shopify.com/static/images/polaris/thumbnail-wc_src.jpg"

></s-thumbnail>

Anchor to Show an empty stateShow an empty state

Show a placeholder when no image is available. This example displays a thumbnail without a source that renders a default icon.

Preview

html

<s-thumbnail alt="No image available" size="base"></s-thumbnail>

Anchor to Adjust the sizeAdjust the size

Adapt thumbnail prominence to different contexts. This example displays small-200, base, and large sizes in a vertical stack.

Preview

html

<s-stack gap="large-100">

<s-thumbnail

src="https://cdn.shopify.com/static/sample-product/House-Plant1.png"

alt="Image of indoor plant"

size="small-200"

></s-thumbnail>

<s-thumbnail

src="https://cdn.shopify.com/static/sample-product/House-Plant1.png"

alt="Image of indoor plant"

size="base"

></s-thumbnail>

<s-thumbnail

src="https://cdn.shopify.com/static/sample-product/House-Plant1.png"

alt="Image of indoor plant"

size="large"

></s-thumbnail>

</s-stack>

Anchor to Handle load eventsHandle load events

Respond to image loading success or failure. This example uses load and error event listeners to update the UI based on the loading result.

Preview

html

<s-stack direction="inline" gap="base" alignItems="center">

<s-thumbnail

id="product-thumbnail"

src="https://cdn.shopify.com/static/sample-product/House-Plant1.png"

alt="Image of indoor plant"

size="small-200"

<s-text id="status-text">Loading...</s-text>

</s-stack>

const thumbnail = document.getElementById('product-thumbnail');

const statusText = document.getElementById('status-text');

thumbnail.addEventListener('load', () => {

statusText.textContent = 'Image loaded';

});

thumbnail.addEventListener('error', () => {

statusText.textContent = 'Failed to load image';

});

</script>

Anchor to Best practicesBest practices

Design for square cropping: Thumbnails automatically crop images to a 1:1 aspect ratio from the center. If your images aren't square, important content near the edges might be cut off.
Maintain visual consistency in groups: Use the same thumbnail size throughout a single list, table, or grid. Mixing sizes creates visual chaos and makes interfaces harder to scan.
Always provide descriptive alternative text: Write alt text that describes the image content, not generic labels like "thumbnail" or "product image." Good alt text helps all merchants understand what they're looking at.
Choose appropriate sizes for your context: Smaller thumbnails work better in dense layouts like tables, while larger sizes suit product-focused interfaces. Consider the merchant's task and the information density when choosing a size.

Anchor to LimitationsLimitations

Thumbnails always render as 1:1 squares and will crop non-square images to fit. The component uses center cropping, which might cut off important image details.
Images can be loaded from remote URLs or local file resources. Cross-origin images require proper CORS headers from the image host.
The component shows a generic placeholder icon when images fail to load or no source is provided. Custom placeholder graphics or branded fallbacks aren't available.
Thumbnails don't include built-in lazy loading. In long lists with many thumbnails, all images load immediately, which might impact performance.

Was this page helpful?