Thumbnail
Display a small preview image representing content, products, or media.
Anchor to propertiesProperties
- Anchor to altaltaltstringstringDefault: `''`Default: `''`
An alternative text description that describe the image for the reader to understand what it is about. It is extremely useful for both users using assistive technology and sighted users. A well written description provides people with visual impairments the ability to participate in consuming non-text content. When a screen readers encounters an
s-image, the description is read and announced aloud. If an image fails to load, potentially due to a poor connection, thealtis displayed on screen instead. This has the benefit of letting a sighted buyer know an image was meant to load here, but as an alternative, they’re still able to consume the text content. Read considerations when writing alternative text to learn more.- Anchor to sizesizesize"small" | "small-200" | "small-100" | "base" | "large" | "large-100""small" | "small-200" | "small-100" | "base" | "large" | "large-100"Default: 'base'Default: 'base'
Adjusts the size the product thumbnail image.
- Anchor to srcsrcsrcstringstring
The image source (either a remote URL or a local file resource).
When the image is loading or no
srcis provided, a placeholder will be rendered.
Anchor to eventsEvents
Learn more about registering events.
- Anchor to errorerrorerrorOnErrorEventHandlerOnErrorEventHandler
- Anchor to loadloadloadCallbackEventListener<typeof tagName> | nullCallbackEventListener<typeof tagName> | null
CallbackEventListener
(EventListener & {
(event: CallbackEvent<T>): void;
}) | nullCallbackEvent
Event & {
currentTarget: HTMLElementTagNameMap[T];
}Preview
Examples
Code
jsx
<s-thumbnail alt="White sneakers" src="https://cdn.shopify.com/static/images/polaris/thumbnail-wc_src.jpg" />html
<s-thumbnail alt="White sneakers" src="https://cdn.shopify.com/static/images/polaris/thumbnail-wc_src.jpg" ></s-thumbnail>Basic usage
Description
Demonstrates a basic thumbnail component with a product image, showing the default base size and an alt text for accessibility.
jsx
<s-thumbnail src="https://cdn.shopify.com/static/sample-product/House-Plant1.png" alt="Product preview" size="base" />html
<s-thumbnail src="https://cdn.shopify.com/static/sample-product/House-Plant1.png" alt="Product preview" size="base" ></s-thumbnail>Empty state
Description
Shows the thumbnail component in an empty state, displaying a placeholder icon when no image source is provided.
jsx
<s-thumbnail alt="No image available" size="base" />html
<s-thumbnail alt="No image available" size="base"></s-thumbnail>Different sizes
Description
Illustrates the various size options for the thumbnail component, showcasing small-200, base, and large sizes in a stack layout.
jsx
<s-stack gap="large-100"> <s-thumbnail src="https://cdn.shopify.com/static/sample-product/House-Plant1.png" alt="Small thumbnail" size="small-200" /> <s-thumbnail src="https://cdn.shopify.com/static/sample-product/House-Plant1.png" alt="Base thumbnail" size="base" /> <s-thumbnail src="https://cdn.shopify.com/static/sample-product/House-Plant1.png" alt="Large thumbnail" size="large" /> </s-stack>html
<s-stack gap="large-100"> <s-thumbnail src="https://cdn.shopify.com/static/sample-product/House-Plant1.png" alt="Small thumbnail" size="small-200" ></s-thumbnail> <s-thumbnail src="https://cdn.shopify.com/static/sample-product/House-Plant1.png" alt="Base thumbnail" size="base" ></s-thumbnail> <s-thumbnail src="https://cdn.shopify.com/static/sample-product/House-Plant1.png" alt="Large thumbnail" size="large" ></s-thumbnail> </s-stack>With event handling
Description
Demonstrates how event handlers like onload or onerror can be attached to the thumbnail component via JavaScript to handle image loading states.
jsx
const [loading, setLoading] = useState(true) return ( <s-stack direction="inline" gap="base" alignItems="center"> <s-thumbnail src="https://cdn.shopify.com/static/sample-product/House-Plant1.png" alt="Product" size="small-200" onLoad={() => setLoading(false)} /> <s-paragraph>{loading ? 'Loading...' : 'Image loaded'}</s-paragraph> </s-stack> )html
<s-stack direction="inline" gap="base"> <s-thumbnail src="https://cdn.shopify.com/static/sample-product/House-Plant1.png" alt="Product" size="small-200" onLoad="setLoading(false)" /> <s-paragraph>Image loaded</s-paragraph> </s-stack>
Anchor to useful-forUseful for
- Identifying items visually in lists, tables, or cards
- Seeing a preview of images before uploading or publishing
- Distinguishing between similar items by their appearance
- Confirming the correct item is selected
Anchor to best-practicesBest practices
small-200: use in very small areassmall: use in small areasbase: use as the default sizelarge: use when thumbnail is a focal point
Anchor to content-guidelinesContent guidelines
Alternative text should be accurate, concise, and descriptive:
- Use "Image of", "Photo of" prefix
- Be primary visual content: "Image of a woman with curly brown hair smiling"
- Include relevant emotions: "Image of a woman laughing with her hand on her face"