Image Gallery ships as a single theme app block. It’s installed automatically when the app is added to a store but doesn’t render anywhere until you add the block to a section through the theme editor. This article covers the block’s settings and how it connects to your galleries — useful when you’re building custom theme sections or templates that include an Image Gallery.

How the Block Renders

The block reads two pieces of metadata the app exposes on the storefront:

Image data - The full list of images you’ve uploaded, with URLs, dimensions, titles, descriptions, and alt text.
Gallery order - A mapping from Gallery ID to that gallery’s image order, layout, desktop and mobile images-per-row, and per-image Mosaic tile sizes.

When a block renders, it looks up the gallery by its Gallery ID, takes the matching images in the stored order, and applies the gallery’s layout. All CSS is scoped to the block instance (via a unique class derived from the block’s ID), so adding multiple blocks to one page never causes style conflicts.

Very large galleries are served differently: past roughly half a megabyte of image data the block renders a stub and hydrates it from the app’s JSON endpoint instead of the metafield, producing the same markup and the same layouts. This is automatic and needs no configuration.

The Gallery ID

Every gallery has a unique Gallery ID in the format gal_abc123. You’ll find it:

On the Install to Theme screen for that gallery, with a one-click copy button.
On the Installation page in the app, which lists every gallery next to its ID.

The Gallery ID is the only required block setting. Without it, the block renders nothing on the storefront and shows a placeholder in the theme editor. Pasted IDs are stripped of stray whitespace, including non-breaking and zero-width characters picked up from rich-text sources.

What the Block Does Not Control

Layout, image order, images per row (desktop and mobile), and Mosaic tile sizes are properties of the gallery and are set in the app. There is no layout override in the theme editor, so the admin canvas and the storefront cannot disagree.

Block Settings

Gallery ID (text) - The prefixed ID of the gallery to render.
Grid tile shape (select) - Square (1:1), Portrait (3:4), Landscape (4:3), or Original ratio. Applies to the Grid layout only.
Images per row (select) - App setting (recommended) or a fixed 2-6. On the app setting, desktop uses the gallery’s desktop count and viewports below 750 px use its mobile count. A fixed number applies at every width.
Gap (px) (range, 0-32) - Spacing between images.
Carousel height (select) - Adapt to image (recommended) leaves slides unconstrained so each keeps its natural ratio; Fixed height pins every slide to one height.
Carousel height (px) (range, 200-800) - Shown only when Carousel height is Fixed height.
Image fit (select) - Fill (crop to fit) or Fit (original ratio). Shown only when Carousel height is Fixed height.
Enable lightbox on click (checkbox) - Default on.
Lightbox background (select) - Dark or Light. Shown only when the lightbox is enabled.
Image titles (select) - Hidden, Show on hover, or Show below image.
Image descriptions (select) - The same three options, applied to the image’s description.

Layout Behaviour on the Storefront

Grid - grid-template-columns: repeat(N, 1fr) with the tile aspect ratio from Grid tile shape; Original ratio drops the ratio and doesn’t crop.
Masonry - The same column count, with row spans computed in JavaScript from each image’s natural ratio once it loads.
Mosaic - Dense grid flow with large (2x2), wide (2x1), and tall (1x2) spans. A tile uses its stored size when one is set; otherwise a built-in repeating pattern applies, keeping roughly half the tiles non-square and drifting the featured tiles across columns at any column count.
Collage - Dense grid flow with every 8th tile (the 1st, 9th, 17th, …) promoted to a 2x2 hero.
Carousel - A flex track showing N slides at once, translating by one slide per arrow click and wrapping at both ends.

Below 750 px, Grid, Masonry, Mosaic, Collage, and the Carousel track all switch to the gallery’s mobile images-per-row.

Adding the Block to a Custom Section or Template

The block has "target": "section", so it can be added inside any section that accepts blocks:

Open the theme editor and navigate to the page or template you’re building.
Click Add block inside any compatible section.
Choose Image Gallery from the Apps category.
Paste a Gallery ID in the block settings.

The deeplink format used by the Install to Theme button is:

/admin/themes/{theme_id}/editor?template=index&addAppBlockId={extension_uuid}/{block_handle}&target=mainSection

The app rewrites this with the merchant’s selected theme ID and copies the Gallery ID to the clipboard so it can be pasted once the editor loads. You can construct the same URL manually to scaffold installs on specific theme templates.

Multiple Blocks per Page

You can add the Image Gallery block to a page as many times as you like. Each instance reads its own Gallery ID, so you can show different galleries side by side, each with its own spacing and caption settings. Styles are scoped per block, so one block’s settings never bleed into another. Two blocks pointed at the same gallery always render the same layout — it belongs to the gallery, not the block.

Theme Block Reference