Product media gallery and lightbox

The Product media gallery is the block that shows a product's images, videos, and 3D models on the product page. It sits inside the Product information section and is connected to the parent product, so it pulls each product's own media automatically. It also drives the full-screen lightbox that opens when a shopper clicks the main image.

Find the gallery settings

In the theme editor, open a product page (switch the editor view to a product).
In the section list, select Product information.
Under it, select Product media gallery to open its settings.

At the top you see the note Connected to the parent product. The block always shows the media of the product being viewed, so there is nothing to assign. For how blocks sit inside a section, see Sections, blocks, and groups.

Settings

Layout

Desktop sets how the media is arranged on larger screens. This choice does not change the mobile slider. The default is Slider.

Slider: one image at a time with arrows and dots.
Thumbnails left: the slider with a column of thumbnails down the left side.
Thumbnails below: the slider with a row of thumbnails underneath.
Stacked: every image stacked in a single column, no slider.
Grid: images arranged in a regular grid.
Highlight: one large lead image, with the rest in a column beside it on wide screens or paired beneath it on narrower ones.

Mobile sets how a shopper moves between images on a phone. Dots shows small markers under the image. Thumbnails shows a row of thumbnail images under the main one. The default is Thumbnails.

Change image on appears only when Desktop is Thumbnails left or Thumbnails below. It sets whether a thumbnail changes the main image on Hover or Click.

Media

Aspect ratio sets the shape of the media frame. The default is Auto.

Auto follows the media's own proportions.
Portrait, Square, and Landscape use the same frame for every image.

Fit height to screen keeps the media within the height of the screen. It is off by default. With Auto, the layouts that show one image at a time (Slider, Thumbnails left, Thumbnails below, and the lead image in Highlight) grow the image to fill that height and trim the overflow. Every other case narrows the frame instead, so nothing is cropped.

Highlight always behaves as if Fit height to screen were on when the product has more than one image, because the column beside the lead takes the width the lead gives up. With a single image the setting decides.

Media fit appears when Aspect ratio is not Auto, or when Fit height to screen is on. Crop fills the frame and trims overflow, while Fit keeps the whole image visible.

Open lightbox on click lets a shopper click the main image to open a full-screen view at a larger size. It is on by default. It also turns on the pointer ring on desktop: over the middle of the image the cursor becomes a magnifier that opens the lightbox, and over the left or right edge it becomes a back or forward arrow that steps the slider. The edge arrows need a slider layout (Slider, Thumbnails left, or Thumbnails below) and more than one visible image, since Stacked, Grid, and Highlight already show everything at once. Turn the setting off to remove the enlarged view and the pointer ring together.

Video

These settings apply to product videos in the gallery.

Enable autoplay: plays videos on their own. Off by default. Its note reads Muted, plays inline., so autoplay videos always start without sound. With it on, Hide controls appears, which removes the native play, pause, and volume controls. A small pause button stays in the corner of the video, so a shopper can always stop a video that started on its own.
Enable video looping: restarts each video when it reaches the end. On by default.

Variant filter

Group media by variant: shows only the images that match the selected variant, so choosing a size or a flavor narrows the gallery to that variant's photos. Off by default. Its note reads Requires alt-text tags on each image, like @color:Sky Blue. Add a tag in that format to each image's alt text in the product admin (the tag names the option and its value, for example @size:500 ml). The match ignores case, images with no tag always stay visible, and an image tagged for more than one option must match all of them. The filter has no effect on a product with no options, so those galleries show everything either way.

Tips

3D models need no setting. If a product has a 3D model in its media, the gallery loads the viewer for it on its own.
For Group media by variant, leave general shots untagged so they stay visible for every variant. If the photos do not switch with the selection, check the spelling and case of the tag against the product's option names and values.
Crop gives the cleanest gallery when all your photos share a shape. Switch to Fit if cropping cuts off part of a product.