# Product gallery and media
> The product's images, videos and 3D models in depth. Covers how the gallery parts work together, galleries that follow the variant, videos outside the gallery, single images by position and image sizes.
Status: Ready (Smootify 2.0)
1.x page: https://docs.smootify.io/docs/ecommerce/products/elements
URL: https://www.smootify.io/docs/build/product-gallery
Updated: 2026-10-10
The gallery shows the media of the Shopify product: its images, and if you want, its videos and 3D models. [Build the product page](https://www.smootify.io/docs/build/product-page) introduces its four parts. This page goes further: how the parts work together, galleries that follow the chosen variant, videos and 3D models outside the gallery, single images by position, and image sizes.
> [!NOTE]
> Everything on this page goes inside `smootify-product`, set up as in [Build the product page](https://www.smootify.io/docs/build/product-page). The images, videos and 3D models come from the product's media in Shopify, so upload them there, not to the Webflow CMS.
## How the parts work together
Put a Div block with `product="gallery"` inside `smootify-product`, and the parts you need inside it.
What Smootify needs:
- the `product="gallery"` element inside `smootify-product`;
- the parts inside that element: `gallery="slider"` on a Webflow Slider, `gallery="lightbox"` and `gallery="lightboxes"` on Lightbox links.
What is up to you:
- which parts you use, and where they sit: thumbnails under the slider or beside it, or no slider at all;
- the layout, the wrappers between the gallery element and its parts, the classes and the styles.
Four common ways to combine the parts:
| Layout | Parts inside `product="gallery"` | A click |
|---|---|---|
| Slider and thumbnails | `gallery="slider"`, `gallery="thumbnails"` | on a thumbnail, moves the slider |
| Slides that open full screen | `gallery="slider"`, with a Lightbox link in its first slide | on a slide, opens its picture full screen |
| A slider with a zoom link | `gallery="slider"`, `gallery="lightbox"` | on the zoom link, opens every picture full screen |
| A grid of pictures, no slider | `gallery="lightboxes"` | on a picture, opens it full screen, then the others |
The parts follow each other: when the visitor moves the slider with its arrows, its dots or a swipe, the matching thumbnail becomes the current one. When the product has nothing to show, the gallery element is hidden.
An element inside the Slider belongs to the slides, not to the gallery. Keep thumbnails and lightbox links outside the Slider. The one exception is a Lightbox link inside the first slide, as here:
```html
```
In purple, the CMS fields: bind the images of the first slide and of the thumbnail to **Image** (or **Image URL**) and their Alt text to **Image Alt**, so the page shows the featured image before Smootify loads.
With the Lightbox link in the first slide, every slide opens full screen, and the lightbox moves through all the slides.
### The slider
`gallery="slider"` goes on a Webflow Slider. Design one slide: Smootify copies the first slide once per picture and removes the other slides.
- **An image** goes on the Image inside the slide. A slide without an Image gets the picture as its background.
- **A video** uploaded to Shopify replaces what is inside the slide with a video player. It plays muted, on a loop, by itself. Add `data-controls` to the slide to give videos the player’s controls instead.
- **A YouTube or Vimeo video** replaces what is inside the slide with its player.
- **A 3D model** shows its preview image until its slide is shown. Only then does the 3D viewer load, so a visitor who never reaches that slide does not download it.
Videos and 3D models are in the slider only with `include-media` on the gallery element (see Videos and 3D models, below).
### Thumbnails
`gallery="thumbnails"` goes on the element that repeats once per picture: an Image, or a Link block or Div block with an Image inside. Design one, and Smootify repeats it in place.
- The thumbnail shows the picture on its Image, or as its background when it has no Image.
- For a video or a 3D model, the thumbnail shows the preview image.
- The current thumbnail gets the class `is-active`. Style it with a combo class.
Every slide, thumbnail and repeated lightbox also gets `data-media-type`, set to `image`, `video`, `external-video` or `model`. Custom CSS can use it, for example to put a play icon on the thumbnails of videos: see [CSS](https://www.smootify.io/docs/developers/css).
### Lightboxes
- **`gallery="lightbox"`** on a Lightbox link opens every picture. The link keeps what you designed in it, such as a zoom icon.
- **`gallery="lightboxes"`** on a Lightbox link repeats the link once per picture, each with its image. They form one group, so the lightbox moves through all of them.
- In a lightbox, a video plays with its controls, a YouTube or Vimeo video plays in its player, and a 3D model shows its preview image.
All the parts and what Smootify writes on them: [gallery parts](https://www.smootify.io/docs/reference/attributes/gallery).
## Galleries that follow the variant
Without any option, the gallery shows every image of the product. When the visitor picks a variant that has an image, the slider moves to that image. Clicking a picture does not change the variant.
To show only the images of the chosen variant, add `only-variant-images` to the gallery element. In Shopify, you link an image to a variant in the variant’s settings. Smootify then groups the images in one of two ways, by position or by alt text.
The options are set per gallery. One gallery on a page can follow the variant while another one shows every picture.
Pick a colour and switch between the two ways to see which images the gallery shows:
Example: a t-shirt in Red, Blue and Green with eight images in this order: 1 a photo of the model (no color), 2-4 Red (2 is the image of the Red variant), 5-6 Blue (5 is the image of Blue), 7-8 Green (7 is the image of Green). By position, Red shows 2, 3, 4; Blue 5, 6; Green 7, 8; image 1 is never shown. By alt text (2-8 end with "# Red", "# Blue", "# Green", 1 has no tag), Red shows 1, 2, 3, 4.
### By position
This is how `only-variant-images` groups the images by default. Each image linked to a variant starts a group, and the group runs until the next linked image.
Take a chair sold in Oak and Walnut, with five images in this order in Shopify:
| Image in Shopify | Linked to | Shown when the visitor picks |
|---|---|---|
| 1. The chair in a room | no variant | only a variant without an image |
| 2. Oak, front | Oak | Oak |
| 3. Oak, detail | no variant | Oak |
| 4. Walnut, front | Walnut | Walnut |
| 5. Walnut, detail | no variant | Walnut |
A variant without an image of its own shows every image. The images before the first linked one belong to no group: once the visitor picks Oak or Walnut, the room picture is gone. For pictures that belong to every variant, group the images by alt text.
### By alt text
Add `variant-images="alt"` next to `only-variant-images`. Each image then goes with the variants that its alt text names after the last `#`. An image without a tag shows for every variant.
- `Oak chair, front # Oak` shows for every Oak variant.
- `Oak chair # Oak / Steel` shows only for the variant with both values. Put a slash with a space on each side between the values, so a value such as `Black/White` stays one value.
- `#Wood_Oak` (the option name, an underscore, the value) also works.
Capital letters and the spaces around the values do not matter, but each value must be one of the variant’s values. You write the alt text in Shopify, on each image.
The alt text is public, tag included: screen readers and search engines read it. Write it so that it makes sense read aloud.
```html
```
## Videos and 3D models
### In the gallery
Add `include-media` to the gallery element. The gallery then shows, in the order of the product’s media in Shopify, the images, the videos uploaded to the product, YouTube and Vimeo videos, and 3D models. Without it, the gallery shows images only.
A 3D model becomes a 3D viewer in the slider only if its file in Shopify is a GLB or glTF file. Without one, its preview image stays in its place.
### Outside the gallery
To show videos in a section of their own, use these attributes on elements inside `smootify-product`:
| Attribute | Put it on | What it shows |
|---|---|---|
| `product="video"` | a Background Video or a Lightbox link | the first video uploaded to the product |
| `product="videos"` | the same | every video, one copy of the element each |
| `product="external-video"` | a Div block or a Lightbox link | the first YouTube or Vimeo video |
| `product="external-videos"` | the same | every YouTube or Vimeo video, one copy each |
| `product="model"` | a Div block | a 3D viewer for each model |
- **On a Lightbox link**, the Image inside shows the video’s preview, and the lightbox plays the video.
- **On a Background Video**, Smootify adds the product’s video to the player inside it.
- **On a Div block**, the YouTube or Vimeo player fills the element. Give the Div block a size in your design.
- **On a Webflow Slider**, `product="videos"` and `product="external-videos"` make one slide per video.
- **A product without videos** of that kind loses the element.
`product="model"` loads the 3D viewer only on a product that has a model. On a product without one, the element stays as you designed it. Its custom attributes that start with `data-` go to the viewer under the name after `data-`: `data-auto-rotate` makes the model turn by itself.
```html
```
## One image by position
`product="specific-image"` shows one image of the product, chosen by its position among the images. Videos and 3D models do not count.
- `index="0"` is the first image, `index="1"` the second, and so on.
- Without `index`, it shows the second image, for example for a card that shows another picture on hover.
- When the product has no image at that position, the element is removed.
Put it on an Image, on a Lightbox link with an Image inside (the lightbox then opens that image), or on another element to use the picture as its background. It works in [product cards](https://www.smootify.io/docs/build/product-cards) and [variant cards](https://www.smootify.io/docs/build/variants-list) too. For the image of the chosen variant, which changes with the variant, use `variant="image"`.
## Image sizes
Without size attributes, the page downloads each Shopify image at its full size. These attributes ask the Shopify CDN for a smaller file. Here on an image of 2000 × 1500 pixels:
Example: a Shopify image of 2000 × 1500 pixels.
| Attribute | What the page downloads | Needs |
|---|---|---|
| `max-width="800"` | the image at most 800 pixels wide: 800 × 600 | nothing else |
| `max-height="800"` | the image at most 800 pixels high: 1067 × 800 | nothing else |
| `crop="center"` | a larger image cropped to both sizes, starting from that point: 800 × 800, cut from the center | `max-width` and `max-height` |
| `pad-color="ffffff"` | a smaller image with the space around it filled with that color: 800 × 600 inside 800 × 800 of white | `max-width` and `max-height` |
Where they go:
- for the slides, on the **Slider** (not on the slide);
- for thumbnails and repeated lightboxes, on the element with the `gallery` attribute;
- for single images, on the element with `product="specific-image"` or `variant="image"`.
They work only on images that Smootify fills from Shopify, not on images bound to a CMS field. Every image they work on: [image size](https://www.smootify.io/docs/reference/attributes/image-size).
## Coming from 1.x
1.x built galleries from `product="images"` or `product="media"` on Sliders and Lightbox links, with `offset` and the site-wide options `showOnlyActiveImages` and `activeImagesMode`. They still work in 2.0, and the [debugger](https://www.smootify.io/docs/start/debugger) on your `.webflow.io` address points them out. The gallery element reads only its own attributes, not the site-wide options.
A 1.x Slider with `product="images"` or `product="media"` follows the chosen variant and the clicks on its thumbnails, also when the page opens on a variant whose image is not the first. This holds for every such Slider of the product, such as a second one for phones. With `showOnlyActiveImages`, each of them shows only the images of the variant, and the Sliders of `product="videos"` and `product="external-videos"` are left as they are.
| 1.x | 2.0 |
|---|---|
| `product="images"` on a Slider | `gallery="slider"` inside `product="gallery"` |
| `product="media"` on a Slider | the same, with `include-media` on the gallery |
| Lightbox links or images that became slider dots | `gallery="thumbnails"` |
| `product="images"` on a Lightbox link | `gallery="lightboxes"` |
| `showOnlyActiveImages: true` | `only-variant-images` |
| `activeImagesMode: "alt"` | `variant-images="alt"` |
| `offset` | none: remove the picture from the product’s media in Shopify, or use `only-variant-images` |
## Before you publish
> [!STUCK]
> - **Videos or 3D models are missing.** Add `include-media` to the `product="gallery"` element.
> - **The first picture disappears when a variant is picked.** With `only-variant-images`, the images before the first linked image belong to no variant. Group the images by alt text instead.
> - **The gallery shows every picture after a move from 1.x.** The gallery ignores `showOnlyActiveImages`. Add `only-variant-images` to the gallery element.
> - **The slides you designed are gone.** Only the first slide is the template: Smootify removes the others.
> - **Image sizes do nothing on the slides.** Put `max-width` and the other size attributes on the Slider, not on the slide.
> - **A 3D model shows only a picture.** In thumbnails and lightboxes a model is always its preview image. In the slider, the model needs a GLB or glTF file in Shopify.
> - **Screen readers read "# Oak" aloud.** The tag is part of the public alt text. Write the alt text as a phrase that ends with the tag.