Choose a version:

Product thumbnail

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

Product thumbnails provide a visual preview of items so customers can quickly identify products. For full-size images, use image. For user profile images, use avatar. To display multiple product images in a compact layout, use image group.

Product thumbnails render at a fixed aspect ratio and use center cropping for non-square images, which might cut off important details near the edges. Cross-origin images require proper CORS headers from the host. Custom placeholder graphics aren't available.

Support

Targets (24)

Supported targets

Anchor to PropertiesProperties

Configure the following properties on the product thumbnail component.

Anchor to alt alt string Default: '': 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 'base' | 'small' | 'small-100' Default: 'base': The size of the product thumbnail image.

'base': Default size that works well in most contexts.

'small': Small thumbnail, good for secondary contexts or tight layouts.

'small-100': Extra small thumbnail for compact displays or dense lists.
Anchor to sizes sizes string: A set of media conditions and their corresponding sizes. Learn more about the sizes attribute.
Anchor to src src string: 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. Learn more about the src attribute.
Anchor to srcSet srcSet string: A set of image sources and their width or pixel density descriptors. Learn more about the srcset attribute. This overrides the src property.
Anchor to totalItems totalItems number: The total number of items that the product thumbnail represents. When this value exceeds 1, the component displays a badge showing the count, useful for representing bundled products or quantities.

Anchor to ExamplesExamples

Anchor to Display a product thumbnailDisplay a product thumbnail

Display a small preview image for a product. This example presents a basic product thumbnail with a source URL and alt text for accessibility.

Display a product thumbnail

A product thumbnail displaying an indoor plant in a gray pot.

html

<s-product-thumbnail

alt="Indoor plant in a gray pot"

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

></s-product-thumbnail>

Anchor to Show an empty stateShow an empty state

Handle products without images gracefully. This example shows an empty thumbnail placeholder alongside product details when no image is available.

html

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

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

<s-stack gap="small">

<s-text type="strong">Custom order</s-text>

<s-text color="subdued">Image unavailable</s-text>

</s-stack>

Anchor to Adjust the sizeAdjust the size

Compare available thumbnail sizes side by side. This example displays the same product at small-100, small, and base sizes aligned along the bottom edge.

html

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

<s-product-thumbnail

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

alt="Indoor plant"

size="small-100"

></s-product-thumbnail>

<s-product-thumbnail

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

alt="Indoor plant"

size="small"

></s-product-thumbnail>

<s-product-thumbnail

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

alt="Indoor plant"

size="base"

></s-product-thumbnail>

</s-stack>

Anchor to Display in an order summaryDisplay in an order summary

Build an order summary with product thumbnails, names, quantities, and prices. This example shows two line items inside a section with each product displayed alongside its details.

html

<s-section>

<s-heading>Order #1234</s-heading>

<s-stack gap="base">

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

<s-product-thumbnail

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

alt="Indoor plant"

size="small"

></s-product-thumbnail>

<s-stack gap="small">

<s-text type="strong">Indoor Plant</s-text>

<s-text color="subdued">Qty: 1 · $24.99</s-text>

</s-stack>

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

<s-product-thumbnail

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

alt="White sneakers"

size="small"

></s-product-thumbnail>

<s-stack gap="small">

<s-text type="strong">White Sneakers</s-text>

<s-text color="subdued">Qty: 1 · $89.00</s-text>

</s-stack>

</s-section>

Anchor to Best practicesBest practices

Use high-quality product images: Use optimized product images that ensure visual clarity and fast loading. Maintain a consistent aspect ratio for product thumbnails to avoid distortion or stretching.
Maintain visual consistency: Keep a consistent visual style for product thumbnails throughout your extension. This consistency helps customers recognize and associate thumbnails with product offerings.
Always provide descriptive alt text: Write alt text that describes the product, such as "Blue cotton t-shirt with crew neck." Avoid generic labels like "product image" or "thumbnail."
Choose appropriate sizes for your context: Smaller thumbnails work better in dense layouts like lists, while larger sizes suit product-focused interfaces. Consider the customer's task and the information density when choosing a size.

Was this page helpful?