Gallery — Configuration Guide

This guide explains how to configure the Gallery section in the theme editor. The section displays a collection of images in a uniform grid, masonry (mosaic) layout, or horizontal strip, with optional captions, links, hover effects, and caption overlays.

Location

Theme editor: Add the "Gallery" section to any page template.
Dedicated page template: templates/page.gallery.json
Section source: sections/gallery.liquid

Section Settings

Layout

Setting	Type	Default	Description
Layout	Select	Grid	`Grid` — uniform rows with merchant-selected aspect ratio. `Mosaic` — masonry/Pinterest-style layout preserving natural image ratios. `Strip` — horizontal scrolling single row.
Columns (desktop)	Number	4	Number of columns on desktop screens. Applies to grid and mosaic variants.
Columns (mobile)	Number	2	Number of columns on mobile screens. Applies to grid and mosaic variants.
Aspect ratio	Select	Square (1:1)	Grid and strip variants. Controls how images are cropped: `Square` (1:1), `Portrait` (4:5), `Landscape` (3:2), or `Natural` (no crop). Mosaic always uses natural ratios regardless of this setting.
Spacing	Select	Medium	Controls the gap between gallery items: `Tight` (6–8px), `Medium` (token-based), `Wide` (32–40px).
Caption style	Select	Below image	How captions display: `Below image` (default text below), `Overlay (bottom)` (gradient overlay at bottom of image), `Overlay (center)` (dark tint with centred text).
Hover effect	Select	None	Desktop-only effect on hover: `None`, `Zoom` (subtle scale up), `Lift` (slight raise with shadow). Automatically disabled when the user prefers reduced motion.
Enable lightbox	Checkbox	Off	When enabled, clicking an image without a link opens a full-screen image viewer with zoom, prev/next navigation, and caption display.

Style

Setting	Type	Default	Description
Color scheme	Color scheme	`scheme-1`	Controls the section's background colour and text colour.
Padding top	Select	Medium	Top spacing: `None`, `Small`, `Medium`, `Large`.
Padding bottom	Select	Medium	Bottom spacing: `None`, `Small`, `Medium`, `Large`.

Image Blocks

Each image in the gallery is an Image block. Add as many as needed. Block order in the editor determines display order on the storefront.

Setting	Type	Description
Image	Image picker	The image to display. Blocks with no image are skipped.
Caption	Text	Optional text shown below or overlaid on the image. Leave blank to hide.
Link	URL	Optional destination URL. Makes the image clickable. Leave blank to disable.
Featured	Checkbox	When checked, this image spans two columns in grid layout. Has no visual effect in mosaic or strip layouts.

How It Works

Grid variant displays all images in a uniform CSS grid. Images are cropped to the selected aspect ratio (default: square). All cells are the same size, creating clean rows. Featured items span two columns.
Mosaic variant displays images in a CSS column-count masonry layout. Each image keeps its natural aspect ratio, so columns have staggered heights — Pinterest-style.
Strip variant displays images in a single horizontal scrolling row with scroll-snap. On desktop, prev/next arrow buttons appear on hover for navigation.
Column count is merchant-controllable for both desktop and mobile. The same setting applies to grid (grid-template-columns) and mosaic (column-count). Strip variant ignores columns — items size automatically.
Spacing controls the gap between items across all variants. Tight is ideal for editorial/lookbook layouts; wide gives each image more breathing room.
Caption styles:
- Below image — small muted text beneath the image (default)
- Overlay (bottom) — white text over a gradient at the bottom of the image
- Overlay (center) — white text centred on a dark tint over the image
Hover effects (desktop only, respects reduced motion preference):
- Zoom — image subtly scales up on hover
- Lift — the entire item lifts up with a soft shadow
Captions also serve as fallback alt text when the image has no explicit alt text set.
Links wrap the image in an anchor tag. When an image has both a link and no alt text, the caption is used as the link's aria-label for accessibility.
Single image — when only one image block has content, the grid collapses to a single centred column with a max-width of 680px.
Color scheme applies a background colour and text colour to the entire section, including caption text.
Lightbox — when enabled, images without a link become clickable. Tapping opens a full-screen overlay with the high-resolution image. Use arrow buttons or keyboard arrows to navigate between images. Click the image to toggle zoom (fit ↔ full resolution with pan). Press ESC or click the backdrop/close button to exit. A counter ("1 / 6") and the image caption are shown below the navigation controls.

Empty-State Safety

If no image blocks exist or all blocks have blank images, the section renders nothing.
Missing captions are simply not rendered — no empty <figcaption> appears.
Missing links result in images without anchor wrappers — no dead links.
Missing alt text falls back to caption text, then to empty alt attribute.

Practical Tips

Consistent ratios: For grid variant, use images that look good when cropped to the selected ratio. Square works well for product shots; landscape for scenery.
Natural mode: Set aspect ratio to "Natural" in grid mode if you want each image to show uncropped but still in uniform columns (effectively Variant B — Mixed Ratios).
Mosaic: Best for collections with varied aspect ratios where you want a dynamic, editorial feel.
Strip: Great for lifestyle or editorial galleries that benefit from horizontal browsing. Arrow buttons appear on desktop hover.
Featured images: Use sparingly in grid layout to create visual hierarchy — featured blocks span two columns, drawing attention to hero images.
Column count: 3–4 works well for desktop product galleries. Use 1–2 for mobile to keep images large enough to be meaningful.
Caption overlays: Best used with darker images or when the caption is short. Overlay center works well for category labels.
Captions: Keep them short — they appear in small text. Good for image credits, product names, or location tags.
Alt text: Set alt text on the image asset itself in Shopify Admin (Files). This is preferred over relying on caption fallback for accessibility.
Lightbox: Best for detailed product shots or editorial photography where customers benefit from viewing full-resolution images. Note that images with link URLs bypass the lightbox — clicking navigates to the link instead.

Troubleshooting

Problem	Solution
Section doesn't appear	Ensure at least one Image block has an image assigned. The section skips rendering when no images are present.
Images look stretched or weirdly cropped	Change the aspect ratio setting. Try "Natural" to show images at their original proportions.
Mosaic looks like a regular grid	Mosaic needs images with different aspect ratios to create the staggered effect. If all images are the same ratio, there's nothing to stagger.
Captions not showing	Check the Image block's Caption field is populated. Empty captions are intentionally hidden.
Colours look wrong	Check the Color scheme setting. Make sure it matches the intended palette for the page context.
Hover effect not visible	Hover effects only appear on desktop with a mouse. They are automatically disabled for touch devices and users who prefer reduced motion.
Strip arrows don't appear	Arrow buttons only render for the Strip layout variant and only appear on desktop hover (hidden on touch devices).
Featured checkbox has no effect	The Featured flag only causes images to span two columns in Grid layout. It has no visual effect in Mosaic or Strip layouts.
Lightbox doesn't open	The lightbox only opens on images without a link URL. If an image has a link, clicking navigates to that URL instead. Also ensure the "Enable lightbox" checkbox is turned on.