Deliver responsive product images

Use the Media.src URL returned by Storefront as the source for product images. Request dimensions appropriate to each layout instead of downloading the original asset for every product card.

1. Select the image

Request image { src } on the variant used by the current product card or option selection. Handle a missing image without hiding the product’s name, price, or availability. See Build product pages for a complete query.

2. Construct a URL safely

The example storefront uses width, quality, and format parameters for Thor image delivery. Use the URL API so an existing query string is preserved.

Image URL

Code in typescript

The width is a layout choice, not the original file width. Choose a small, reusable set of widths for your product grid and gallery. Keep the source URL returned by Thor; do not build a CDN path from a file name.

3. Render responsive sizes

Use this component together with the helper above:

Product image

Code in tsx

Adjust sizes to match your actual grid and the aspect ratio to match your design. The example reserves a square area and contains the product inside it. Use lazy loading for offscreen images; handle a prominent initial image according to your framework’s loading guidance.

Next.js integration

The reference storefront provides src/components/thor-image/thor-image.tsx, a wrapper around the framework image component with a Thor loader. Keep image URL construction in one helper when customizing it. Avoid appending a second ? when the source already has parameters.

Verify

Inspect network requests at narrow and wide viewport sizes and on a high-density display. Confirm the browser selects an appropriate width, the layout does not jump, missing images have a useful fallback, and switching variants changes the correct image. See Product media for association and gallery ownership.