Skip to content
Tutorials Center
My learning

Topics

Lesson 24 of 61 ยท Products, Collections and Variants

Product Media: Images, Video and 3D

Show Shopify product media correctly: media types, image_url and image_tag, srcset and sizes, video and 3D tags, alt text and featured media per variant.

Photos sell products. A product page with sharp, fast images converts better than one with heavy, blurry or missing ones, and the images are usually the biggest files on the page. In Shopify, product pictures, videos and 3D models are all media, attached to the product in the admin. Your theme decides which tag to print for each type and, for images, which sizes to offer the browser.

This lesson covers the media object, the image_url and image_tag filters, how srcset and sizes work together, the tags for video and 3D, alt text, and how to show the right image for the chosen variant. It follows the gallery you sketched in Building the Product Page.

Media objects and the image filters exist only in Shopify's Liquid, so theme code in this lesson is read-only and written for current Online Store 2.0 themes. The live examples are JavaScript stand-ins: one builds a srcset the way image_tag does, one imitates how a browser picks a candidate from it. Example image URLs are made up. Exact default widths and attribute behavior of the real filters can change, so always pass the values you want explicitly and check the current reference.

The media object

product.media is an ordered list. The merchant drags items to reorder them, and the first item is the featured media. Each entry has a media_type:

media_type What it is Useful properties
image an uploaded picture alt, width, height, preview_image
video video hosted by Shopify sources, preview_image, alt
external_video YouTube or Vimeo link host, external_id, preview_image
model 3D model sources, preview_image

Every type has an id, a position and a preview_image (a still picture), so you can always show something in a thumbnail strip. Because the list mixes types, a gallery loop branches on media.media_type.

flowchart TB
  M["media in product.media"] --> Q{"media_type?"}
  Q -->|image| I["image_url, then image_tag<br/>with srcset"]
  Q -->|video| V["video_tag"]
  Q -->|external_video| E["external_video_tag"]
  Q -->|model| X["model_viewer_tag"]

One loop, four branches. Each media type has its own tag.

Images: image_url and image_tag

Two filters work as a pair. image_url turns an image into a CDN URL at the width you ask for. image_tag wraps that URL in a complete <img> element.

LIQUID
{{ media.preview_image | image_url: width: 800 }}
{# https://cdn.example/.../mug.jpg?v=1&width=800 #}

{{ media.preview_image
   | image_url: width: 1200
   | image_tag: widths: '400, 800, 1200', sizes: '(min-width: 990px) 50vw, 100vw', loading: 'lazy' }}

image_tag adds width and height attributes when it knows the image size. Those attributes let the browser reserve space before the image downloads, which prevents layout shift (the CLS metric explained in Theme Performance and Core Web Vitals). Other attributes you pass (such as class, loading, fetchpriority or alt) become HTML attributes. If you do not pass alt, the media's own alt text is used.

srcset and sizes

A single image URL forces every device to download the same file. A phone with a 390 px screen should not download a 2000 px picture. srcset offers a list of candidate files, and sizes tells the browser how wide the image will be on the page:

HTML
<img
  src="https://cdn.example/mug.jpg?v=1&width=1200"
  srcset="
    https://cdn.example/mug.jpg?v=1&width=400 400w,
    https://cdn.example/mug.jpg?v=1&width=800 800w,
    https://cdn.example/mug.jpg?v=1&width=1200 1200w"
  sizes="(min-width: 990px) 50vw, 100vw"
  width="1200" height="1200"
  alt="Blue stoneware mug on a wooden table"
  loading="lazy">

The w numbers are the pixel widths of the files. The browser combines three facts: the slot width from sizes (for a 1000 px wide window, 50vw is 500 px), the device pixel ratio (a 2x screen needs 1000 pixels to look sharp), and the candidates available. It then picks a suitable file. You do not choose which one, and that is the point: the browser knows the screen, the connection and the cache; you only describe the layout honestly.

Two rules keep this reliable:

  1. sizes must match your CSS. If the gallery is half the window on desktop and full width on phones, say exactly that. A wrong sizes makes the browser download too much or too little.
  2. Never list widths larger than the original image. Shopify will not upscale, so asking for 3000 px of a 1200 px file only creates duplicates. The theme should cap widths at media.width.

Loading priority

Not all images should load lazily. The first gallery image is usually the Largest Contentful Paint element, and lazy-loading it delays it:

LIQUID
{%- if forloop.first -%}
  {{ image | image_url: width: 1200 | image_tag: widths: '600, 900, 1200', sizes: sizes, loading: 'eager', fetchpriority: 'high' }}
{%- else -%}
  {{ image | image_url: width: 1200 | image_tag: widths: '600, 900, 1200', sizes: sizes, loading: 'lazy' }}
{%- endif -%}

Images below the fold (thumbnails, later gallery slides) should be lazy. This single distinction often moves a Lighthouse score noticeably.

Video and external video

Videos uploaded to Shopify arrive as video media with several sources. The video_tag filter builds a <video> element with those sources and a poster image:

LIQUID
{{ media | video_tag: controls: true, image_size: '1100x', loop: false, muted: false, preload: 'none' }}

preload: 'none' avoids downloading video data until the shopper presses play. Autoplaying videos should be muted and loop quietly, and never be the only way to learn something about a product.

YouTube and Vimeo links arrive as external_video media. Use external_video_tag, which prints an <iframe>:

LIQUID
{{ media | external_video_tag }}

An iframe from a third party brings its own scripts and weight. A common pattern is to show the preview_image first and only add the iframe when the shopper clicks, which improves performance considerably.

3D models

Products can carry a 3D model (a GLB or USDZ file). The model_viewer_tag filter prints a <model-viewer> custom element:

LIQUID
{{ media | model_viewer_tag: image_size: '1100x', reveal: 'interaction' }}

That element is a web component, so the page must also load a model-viewer script; the reference themes include the required scripts and styles, and you should copy their approach rather than inventing one. reveal: 'interaction' waits for the shopper to interact, so the heavy model does not load automatically. Treat 3D as an enhancement: always have the preview_image ready as a fallback for devices that cannot show it.

Alt text

Alt text describes an image for people who cannot see it, such as screen reader users, and it is shown when an image fails to load. Merchants write alt text per media item in the admin, and media.alt returns it. In your theme:

  • let image_tag use the media alt automatically;
  • if media.alt is blank, think about whether the image is decorative (then alt="" is correct) or informative (then the merchant needs to be prompted to add text);
  • describe what the picture shows, not "image of". Good: "Blue stoneware mug with a wide handle". Weak: "mug.jpg".

Accessibility in Themes goes further. Alt text also feeds image search, which ties into SEO in Themes.

A merchant can link a media item to a variant, so choosing "Green" shows the green mug. In Liquid, variant.featured_media is that item, or blank. A typical gallery marks each slide with the media id and lets JavaScript reveal the right one:

LIQUID
{%- assign start_media = current_variant.featured_media | default: product.featured_media -%}

<ul class="gallery">
  {%- for media in product.media -%}
    <li data-media-id="{{ media.id }}" {% if media.id == start_media.id %}class="is-active"{% endif %}>
      ...
    </li>
  {%- endfor -%}
</ul>

When the variant changes, your script reads the new variant's featured_media.id from the variants JSON (see Variants and Option Pickers) and activates the slide whose data-media-id matches. Be consistent about which id you use: use media.id everywhere, and do not mix it with ids from the older variant.featured_image.

Stand-in: building a srcset

This stand-in does the arithmetic image_tag does for you. Given a made-up CDN URL, the original width and a list of wanted widths, it keeps only widths that do not exceed the original, builds the srcset, and prints the <img> tag. Only the URL shape is invented; the logic is what you would reason about in a real theme.

JS Stand-in: build a srcset from widths

Press Run (or Ctrl + Enter) to see the console output here.

No output.

The original is 1000 px wide, so the 1200 and 1600 candidates are dropped and the original width is added as the largest file. Because the first image is the likely LCP element, it is eager with a high fetch priority.

Stand-in: how a browser picks a file

The browser's selection is not magic. This second stand-in follows the rule of thumb: work out the slot width from sizes, multiply by the device pixel ratio, and choose the smallest candidate that is at least that wide (or the largest, if none is). Real browsers may also consider cached files and connection, so treat this as a model.

JS Stand-in: which candidate does the browser choose?

Press Run (or Ctrl + Enter) to see the console output here.

No output.

The table shows how the same markup serves very different needs, and why an honest sizes value matters.

Stand-in: one loop, four media types

The last stand-in renders the gallery loop from the diagram. The tags are simplified text, not the real filter output, but the branching and the alt-text check follow what you would do in Liquid.

JS Stand-in: render media by type

Press Run (or Ctrl + Enter) to see the console output here.

No output.

Practical checklist

  • Pass widths and a truthful sizes for every responsive image.
  • Make the first gallery image eager with fetchpriority: 'high'; make the rest lazy.
  • Do not request widths beyond the original image.
  • Provide width and height (via image_tag) to prevent layout shift.
  • Load video and 3D only on interaction where possible.
  • Use meaningful alt text, and give the editor a sensible fallback for missing images.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. What does the sizes attribute tell the browser?

    sizes describes the display width of the image slot. The browser combines it with srcset and the device pixel ratio to choose a file.
  2. 2. Which image in a product gallery should normally NOT be lazy-loaded?

    The first visible image is usually the Largest Contentful Paint element. Lazy-loading it delays the page; use eager with a high fetch priority.
  3. 3. Which filter prints the element for a YouTube media item?

    YouTube and Vimeo items are external_video media, rendered as an iframe with external_video_tag.
  4. 4. A product image is decorative and adds no information. What alt text is correct?

    A decorative image gets alt="" so screen readers skip it. Informative images need a real description.

Summary

  • product.media mixes images, videos, external videos and 3D models; branch on media_type.
  • image_url makes a sized CDN URL and image_tag builds the <img> with srcset, sizes, and width and height.
  • An honest sizes plus sensible widths (never above the original) lets the browser download only what it needs.
  • Load the first image eagerly, everything else lazily, and defer heavy video and 3D until the shopper asks.
  • Write real alt text, and use variant.featured_media with data-media-id to show the right picture per variant.

Next, move from one product to many in Collection Pages: Sorting, Filtering and Pagination.