---
title: Product thumbnail
description: >-
The product thumbnail component shows a small product image alongside line
items and recommendations. Use product thumbnails in carts, bundles, upsells,
and compact lists.
api_version: 2026-04
api_name: checkout-ui-extensions
source_url:
html: >-
https://shopify.dev/docs/api/checkout-ui-extensions/latest/web-components/media-and-visuals/product-thumbnail
md: >-
https://shopify.dev/docs/api/checkout-ui-extensions/latest/web-components/media-and-visuals/product-thumbnail.md
---
# Product thumbnail
The product thumbnail component shows a small product image alongside line items and recommendations. Use product thumbnails in carts, bundles, upsells, and compact lists.
Product thumbnails support size variants, quantity badges, and alt text. For larger illustrative images, use [image](https://shopify.dev/docs/api/checkout-ui-extensions/latest/web-components/media-and-visuals/image).
Product thumbnails render at a fixed aspect ratio and use center cropping for non-square images. Custom placeholder graphics aren't available — a generic placeholder shows when images fail to load or no source is provided.
### Support Targets (29)
### Supported targets
* [purchase.checkout.actions.render-before](https://shopify.dev/docs/api/checkout-ui-extensions/2026-04/targets/checkout/navigation#navigation-target)
* [purchase.checkout.block.render](https://shopify.dev/docs/api/checkout-ui-extensions/2026-04/targets/checkout/block#block-target)
* [purchase.checkout.cart-line-item.render-after](https://shopify.dev/docs/api/checkout-ui-extensions/2026-04/targets/checkout/order-summary#line-item-targets)
* [purchase.checkout.cart-line-list.render-after](https://shopify.dev/docs/api/checkout-ui-extensions/2026-04/targets/checkout/order-summary#checkout-cart-line-list-)
* [purchase.checkout.contact.render-after](https://shopify.dev/docs/api/checkout-ui-extensions/2026-04/targets/checkout/information#information-target)
* [purchase.checkout.delivery-address.render-after](https://shopify.dev/docs/api/checkout-ui-extensions/2026-04/targets/checkout/shipping#render-after-delivery-address-)
* [purchase.checkout.delivery-address.render-before](https://shopify.dev/docs/api/checkout-ui-extensions/2026-04/targets/checkout/shipping#delivery-address-targets)
* [purchase.checkout.footer.render-after](https://shopify.dev/docs/api/checkout-ui-extensions/2026-04/targets/checkout/footer#footer-target)
* [purchase.checkout.header.render-after](https://shopify.dev/docs/api/checkout-ui-extensions/2026-04/targets/checkout/header#header-target)
* [purchase.checkout.payment-method-list.render-after](https://shopify.dev/docs/api/checkout-ui-extensions/2026-04/targets/checkout/payment#render-after-payment-methods-)
* [purchase.checkout.payment-method-list.render-before](https://shopify.dev/docs/api/checkout-ui-extensions/2026-04/targets/checkout/payment#payment-targets)
* [purchase.checkout.pickup-location-list.render-after](https://shopify.dev/docs/api/checkout-ui-extensions/2026-04/targets/checkout/local-pickup#render-after-pickup-locations-)
* [purchase.checkout.pickup-location-list.render-before](https://shopify.dev/docs/api/checkout-ui-extensions/2026-04/targets/checkout/local-pickup#location-list-targets)
* [purchase.checkout.pickup-location-option-item.render-after](https://shopify.dev/docs/api/checkout-ui-extensions/2026-04/targets/checkout/local-pickup#location-option-item-target)
* [purchase.checkout.pickup-point-list.render-after](https://shopify.dev/docs/api/checkout-ui-extensions/2026-04/targets/checkout/pickup-points#render-after-pickup-points-)
* [purchase.checkout.pickup-point-list.render-before](https://shopify.dev/docs/api/checkout-ui-extensions/2026-04/targets/checkout/pickup-points#pickup-points-targets)
* [purchase.checkout.reductions.render-after](https://shopify.dev/docs/api/checkout-ui-extensions/2026-04/targets/checkout/order-summary#checkout-reductions-after-)
* [purchase.checkout.reductions.render-before](https://shopify.dev/docs/api/checkout-ui-extensions/2026-04/targets/checkout/order-summary#reductions-targets)
* [purchase.checkout.shipping-option-item.details.render](https://shopify.dev/docs/api/checkout-ui-extensions/2026-04/targets/checkout/shipping#shipping-option-item-targets)
* [purchase.checkout.shipping-option-item.render-after](https://shopify.dev/docs/api/checkout-ui-extensions/2026-04/targets/checkout/shipping#render-after-shipping-option-)
* [purchase.checkout.shipping-option-list.render-after](https://shopify.dev/docs/api/checkout-ui-extensions/2026-04/targets/checkout/shipping#render-after-shipping-options-)
* [purchase.checkout.shipping-option-list.render-before](https://shopify.dev/docs/api/checkout-ui-extensions/2026-04/targets/checkout/shipping#shipping-option-list-targets)
* [purchase.thank-you.announcement.render](https://shopify.dev/docs/api/checkout-ui-extensions/2026-04/targets/thank-you/announcement#thank-you-announcement-)
* [purchase.thank-you.block.render](https://shopify.dev/docs/api/checkout-ui-extensions/2026-04/targets/thank-you/block#block-target)
* [purchase.thank-you.cart-line-item.render-after](https://shopify.dev/docs/api/checkout-ui-extensions/2026-04/targets/thank-you/order-summary#line-item-targets)
* [purchase.thank-you.cart-line-list.render-after](https://shopify.dev/docs/api/checkout-ui-extensions/2026-04/targets/thank-you/order-summary#thank-you-cart-line-list-)
* [purchase.thank-you.customer-information.render-after](https://shopify.dev/docs/api/checkout-ui-extensions/2026-04/targets/thank-you/information#information-target)
* [purchase.thank-you.footer.render-after](https://shopify.dev/docs/api/checkout-ui-extensions/2026-04/targets/thank-you/footer#footer-target)
* [purchase.thank-you.header.render-after](https://shopify.dev/docs/api/checkout-ui-extensions/2026-04/targets/thank-you/header#header-target)
#### Use cases
* **Cart line items**: Show product images in the cart summary to help buyers confirm their selections.
* **Bundle indicators**: Display a thumbnail with a `totalItems` badge to indicate how many items a bundle contains.
* **Compact layouts**: Render small thumbnails in condensed line-item lists where space is limited.
* **Upsell suggestions**: Present recommended products with thumbnails alongside their names and prices.
***
## Properties
Configure the following properties on the product thumbnail component.
* **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](https://www.shopify.com/ca/blog/image-alt-text#4) and the [alt attribute](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/img#alt).
* **size**
**'small' | 'base' | '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.
* **sizes**
**string**
A set of media conditions and their corresponding sizes. Learn more about the [sizes attribute](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/img#sizes).
* **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](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/img#src).
* **srcSet**
**string**
A set of image sources and their width or pixel density descriptors. Learn more about the [srcset attribute](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/img#srcset). This overrides the `src` property.
* **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.
***
## Examples
### Show a product image with a quantity badge
Show a small product image with a quantity badge. This example renders an `s-product-thumbnail` with `totalItems` set to 2, indicating multiple items in the bundle.
## Show a product image with a quantity badge
## html
```html
```
### Show an empty state
Show a placeholder when no image is available. This example displays a product thumbnail without a source that renders a default icon.
## html
```html
```
### Display a compact product thumbnail
Render a small product image for compact line-item layouts. This example configures `size="small"` and a descriptive `alt` attribute for accessibility.
## html
```html
```
### Show a compact bundle thumbnail
Display a small product thumbnail with a quantity badge for bundled items. This example uses `size="small"` and `totalItems="3"` to show a compact bundle with an item count badge.
## html
```html
```
***
## Best practices
* **Provide descriptive alt text**: Write descriptive alt attributes that describe the product, including variant details like size and color. Avoid generic labels like “shirt” or “book”. See Shopify's [alt text guidance](https://www.shopify.com/ca/blog/image-alt-text) to learn more about alt text best practices.
* **Size thumbnails for your context**: Smaller thumbnails work better in dense layouts like lists, while larger sizes suit product-focused interfaces like a recommended product block. Consider the buyer's task and the information density when selecting a size.
* **Use quantity badges appropriately**: Set `totalItems` only when the thumbnail represents a bundle or multi-quantity line item.
* **Maintain visual consistency**: Keep a consistent visual style and aspect ratio for product thumbnails throughout your extension. This consistency helps buyers recognize and associate thumbnails with product offerings.
* **Optimize for visual clarity and loading time**: Choose a resolution and image quality that provide visual clarity while maintaining fast load times. For fast, reliable delivery during checkout, consider hosting images from Shopify's [CDN](https://cdn.shopify.com/).
***