The gallery lightbox: keys, swipe, captions and video

Every gallery app has a lightbox and almost nobody documents what it does beyond "click to enlarge". That leaves merchants guessing about the things shoppers actually notice: whether the arrow keys work, what happens on a phone, whether the caption comes along, why a video behaves differently from a photo. This guide walks through the Snug Gallery lightbox decision by decision, as it is built, so you know what your shoppers get and which two switches change it.

The two settings, and where they are

In the theme editor, every gallery block has a Lightbox heading with two checkboxes. Open images in a lightbox is on by default; turn it off and clicking a tile does nothing for images, while videos play in place instead of opening a viewer. Show captions in the lightbox is also on by default and controls whether the caption title and text appear under the enlarged image. Both are per block: a lookbook on the home page and a grid on an About page can make different choices.

That is the entire list. There is no setting for thumbnails strip, zoom level or slideshow timer because the lightbox has none of those; the trade-offs behind that are at the end of this guide.

What opens it

Each tile is a real button, not a div with a click handler, and its accessible label is Open image: followed by the alt text, or Play video: for a video. Screen readers announce exactly that, and the Tab key reaches every tile in order. Clicking or pressing Enter opens the viewer at that item.

One kind of tile does not open the lightbox: an image you have given a link to. On a paid plan, when an item has a link URL, the tile is rendered as a plain link to that page instead of a button, because an image that says "shop the collection" should go to the collection. The clickable images guide covers the trade-off. Linked items still appear in the viewer if a shopper arrives at them with the arrows from a neighbouring image.

Which image loads

The grid serves small, responsive versions of each image. The viewer asks Shopify's image CDN for a version 2,048 pixels wide, which is the largest size most screens can use and well above what a phone can display. Shopify generates it on demand from the original you uploaded, so the viewer never shows a soft, upscaled thumbnail, and it never downloads your 24-megapixel original either.

While one image is on screen, the next one in the sequence is requested quietly in the background, so pressing the arrow usually shows the neighbour at once. Only the next image is preloaded, not the whole gallery, and videos are never preloaded. The viewer element itself is created the first time someone opens it; a page where nobody clicks pays nothing for it.

The image is sized to fit: at most the viewport width minus 128 pixels and the viewport height minus 140 pixels on desktop, so the close and arrow buttons never overlap the picture, and the full viewport width on screens under 750 pixels. Portrait and landscape images both fit inside that box without cropping.

Moving between items

A counter in the top left reads 3 / 12 so shoppers know where they are. Previous and Next buttons sit at the edges on desktop; both are hidden when the gallery has a single item. The sequence wraps: Next on the last image goes to the first.

On screens under 750 pixels wide the arrow buttons are hidden and the viewer listens for a horizontal swipe instead. A swipe of more than 40 pixels moves one item in that direction; shorter movements are ignored so a shaky tap does not change the image. Vertical scrolling is left to the browser.

On a keyboard, Left and Right arrows move, Escape closes, and Tab cycles only through the viewer's own controls: Close, Previous, Next and, for a video, the player. Focus cannot wander back to the page behind the dark backdrop. When the viewer opens, focus lands on the Close button; when it closes, focus returns to the exact tile that opened it, so a keyboard user carries on from where they were. The accessibility checklist lists what else the gallery does to meet the European Accessibility Act.

Closing it

Four things close the viewer: the Close button, Escape, a click on the dark backdrop, and a click on the empty area around the image inside the figure. Clicking the image itself does nothing, which avoids closing the viewer by accident when a shopper taps to look closer. The backdrop is near-black at 92 percent opacity, fades in and out over a quarter of a second, and the page behind stops scrolling while it is open so the gallery is still where the shopper left it afterwards.

If the shopper's operating system asks for reduced motion, the fade is removed and the viewer appears and disappears instantly. The same preference also stops the slider autoplay, as the slider autoplay guide explains.

Captions in the viewer

With Show captions in the lightbox on, the caption title appears in bold on its own line under the image and the caption text below it, centred and limited to about sixty characters per line so a long description wraps into a readable column rather than a single strip across the screen. An item with no caption shows nothing; the space collapses rather than leaving an empty bar.

The caption shown in the viewer is independent of the caption style you chose for the grid. A gallery that hides captions in the grid for a clean look can still show them enlarged, and vice versa. Alt text is not displayed anywhere; it goes into the image's alt attribute for screen readers and search engines, as described in the captions guide.

Videos behave a little differently

A video tile opens the viewer with a player in place of the image, sized to the video's own aspect ratio so a vertical clip is tall and narrow rather than letterboxed into a widescreen box. Uploaded videos start playing as soon as the viewer opens; YouTube and Vimeo videos load in their own embedded player.

While a native video player has focus it keeps its own keyboard shortcuts, so Space pauses and the arrow keys seek within the clip instead of jumping to the next item. Escape and Tab still belong to the viewer. Moving to another item stops and removes the player, so audio never continues behind the next image.

With the lightbox switched off, clicking a video swaps the poster for the player right there in the grid, and it plays in place. The video gallery guide compares uploading to Shopify with embedding from YouTube or Vimeo.

Filtered galleries and protected images

If the gallery has tag filters and a shopper has narrowed it to one tag, the viewer only cycles through the visible items. Hidden ones are skipped and the counter shows the filtered total, so a shopper looking at the twelve "kitchen" photos sees 1 / 12, not 1 / 80. The filtered gallery link guide explains how to send people straight to such a view.

When right-click protection is on for the block, it applies inside the viewer too: the context menu is blocked, the image cannot be dragged out, and text selection is off. The image protection guide is honest about what that does and does not prevent; the viewer simply does not undo it.

What it deliberately leaves out

No pinch zoom beyond what the browser offers, no thumbnail strip, no autoplaying slideshow, no share bar. Each of those adds script that every page with a gallery would download, and most of them get in the way on a phone, where the viewer is a full-screen image with a swipe. The gallery script as a whole stays small enough to be served by Shopify's CDN with the theme, which is the point of the page speed guide. If you need a product-level zoom with magnification, that belongs on the product page media, not in a gallery.

Frequently asked questions

Can shoppers zoom into the enlarged image?

The viewer shows a 2,048 pixel wide version fitted to the screen, which on most displays is already larger than the visible area allows. There is no additional magnifier; on phones the browser's own pinch zoom still works on the page.

Why do my linked images not open in the lightbox?

An image with a link URL is rendered as a link so that clicking it goes where you pointed it. Remove the link from the item in the app and the tile becomes a lightbox button again. On the Free plan links are not rendered at all, so every image tile opens the viewer.

The arrows are missing on my phone. Is something broken?

No. Under 750 pixels the Previous and Next buttons are hidden to leave the image unobstructed, and a horizontal swipe of more than 40 pixels moves between items instead.

Does the lightbox show the caption even if the grid hides captions?

Yes, if Show captions in the lightbox is on. The two caption settings are independent, so a clean grid can still show the title and text when an image is enlarged.