Product gallery and media

The gallery shows the media of the Shopify product: its images, and if you want, its videos and 3D models. Build the 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.

How the parts work together

Put an element 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 an element that holds a [slider-track], gallery="lightbox" and gallery="lightboxes" on a[lightbox-item] 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:

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 an a[lightbox-item] link inside the first slide, as here:

---
const first = p.images[0];
---
<div product="gallery">
  <div gallery="slider">
    <div slider-track>
      <div><a href={first.url} lightbox-item><img src={first.url} alt={first.altText || p.name} /></a></div>
    </div>
  </div>
  <img gallery="thumbnails" src={first.url} alt={first.altText || p.name} />
</div>

Render the first picture of the entry in the first slide and in the thumbnail, so the page shows the featured image before Smootify loads.

With the link in the first slide, every slide opens full screen, and the viewer moves through all the slides.

The slider

gallery="slider" goes on an element that holds a [slider-track], whose children are the slides. Write one slide: Smootify copies the first slide once per picture and removes the other slides. Smootify moves between the slides by scrolling the track, so the site’s CSS gives the track overflow-x: auto and scroll-snap-type. The optional [slider-prev] and [slider-next] buttons and [slider-dots] element go inside the slider element: see Write components. The arrows are disabled on the first and last slide, and the current dot gets aria-current="true".

• 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 <img>, or an <a> or <div> with an <img> inside. Write 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 and aria-current. Style it in the component’s CSS.

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.

Lightboxes

• gallery="lightbox" on an a[lightbox-item] link opens every picture: the link takes the first media, and Smootify adds a hidden a[lightbox-item] after it for each other media, all in one group. The link keeps what you wrote in it, such as a zoom icon.
• gallery="lightboxes" on an a[lightbox-item] link repeats the link once per picture, each with its image. They form one group.
• Smootify writes the href of the full-size media on each link, with data-media-type and data-lightbox-group. For a video, an external video or a 3D model, the href is its preview image. Smootify does not draw the viewer: the site’s own, a library or a <dialog>, reads the links of a group and reads them again on smootify:render. See Write components.

All the parts and what Smootify writes on them: gallery parts.

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 variant-images to the gallery element, with no value. 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:

By position

This is how variant-images groups the images when it has no value. 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:

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

Give the attribute the value alt: variant-images="alt". Each image then goes with the variants that its alt text names after the last #. An image without a tag shows for every variant. With include-media, videos, YouTube and Vimeo videos and 3D models are grouped the same way, by their own alt text.

• 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 and video.

The alt text is public, tag included: screen readers and search engines read it. Write it so that it makes sense read aloud.

---
const first = p.images[0];
---
<div product="gallery" include-media variant-images="alt">
  <div gallery="slider">
    <div slider-track>
      <div data-controls><img src={first.url} alt={first.altText || p.name} /></div>
    </div>
  </div>
</div>

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:

• On an a[lightbox-item] link, the <img> inside shows the video’s preview, and the link gets data-media-type. The site’s viewer decides how to play it.
• On an element with a <video> inside, Smootify adds the product’s video sources to that <video>.
• On an element for a YouTube or Vimeo video, the player fills the element. Give the element a size in your design.
• In a slider, product="videos" and product="external-videos" become a slider when they contain a [slider-track]: one slide per video, each a copy of the first slide whose content is replaced by the video, so anything you design inside the slide is not kept. Smootify runs the [slider-prev], [slider-next] and [slider-dots] inside the element. On a product without videos of that kind, the first slide stays as you wrote it.
• 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 wrote it. Its attributes that start with data- go to the viewer under the name after data-: data-auto-rotate makes the model turn by itself.

<div>
  <a href="#" lightbox-item product="videos"><img alt=""></a>
  <div product="external-videos"></div>
</div>

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 <img>, or on another element to use the picture as its background. It works in product cards and variant cards 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:

Where they go:

• for the slides, on the gallery="slider" element (not on a 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 an <img> that Smootify does not fill. Every image they work on: image size.

Before you publish