Snug Gallery on Hydrogen or a headless Shopify store

A question that arrives every few weeks, usually from a developer rather than a merchant: we are moving the storefront to Hydrogen, does Snug Gallery come with us? The honest answer is in two parts. The gallery you see on a page, with its lightbox, filters and shop-the-look pins, is a theme app extension and does not run in Hydrogen or any other headless storefront. The galleries themselves, every image, caption, link and tag you have arranged, are ordinary Shopify metaobjects and files that belong to your store, and a headless storefront can read them the same way it reads products. This guide sets out exactly where that line falls, what a Hydrogen team gets for free, what they would have to build, and what to do if your store is only partly headless.

Why the block does not render in Hydrogen

Snug Gallery adds a gallery to a page as an app block in the theme editor. That block is Liquid: it reads the gallery you picked in its settings, loops over the images, and writes the HTML, with a small script for the lightbox, slider and filter bar. Liquid is rendered by Shopify's Online Store channel. Hydrogen is a React application you host yourself, with its own routing and rendering, and it never asks Shopify to render Liquid. So there is no place for the block to appear, and no amount of configuration changes that. The same is true of any theme app extension, including the app embeds you may be used to from analytics and chat apps.

This is also why the theme switching guide is reassuring and this one is less so. Switching from one Online Store theme to another keeps the Liquid renderer; you re-add the block and the gallery is back. Switching to Hydrogen removes the renderer entirely.

What a headless store still has

Every gallery is a metaobject of a type reserved for the app, and every image in it is a second metaobject that points at a file in your store's Files library. Shopify exposes metaobjects to the Storefront API when their definition grants storefront read access, which Snug Gallery's does, because the Liquid block needs the same access to render them. A Hydrogen route can therefore query the galleries directly, no app server involved, with the same storefront token it already uses for products and collections.

The gallery metaobject carries the title, the layout you chose, the sort mode, and whether customer photo submissions are enabled. Each image metaobject carries the file reference, alt text, a caption title and caption text, an optional link URL and a new-tab flag, the shop-the-look hotspots, an optional video URL for video tiles, and the tags used by the filter bar. The block settings reference describes what each of those does in the theme version; in Hydrogen they are simply data for your component to interpret.

The images are the ordinary Shopify files the files versus app-hosted guide describes, served from Shopify's CDN with the usual width and format parameters. Nothing is hosted on our servers, so there is no second CDN to point at and no dependency on the app being reachable when a page renders.

What a Hydrogen team would have to build

The presentation. Layouts (grid, masonry, carousel, collage), the lightbox with keyboard and swipe, the tag filter bar, lazy loading, the slider's autoplay and reduced-motion handling, captions, Pinterest buttons, shop-the-look cards that add a variant to the cart. All of that lives in the block's Liquid and script, and a Hydrogen store needs a React equivalent. For a simple grid with a lightbox that is an afternoon with the data above and a component library. For hotspots that open a product card and add to cart, it is more, because the hotspot coordinates are stored as positions on the image and the product references have to be resolved through the Storefront API.

There is no official Hydrogen component for Snug Gallery today, and we would rather say so than hint at one. If you are a Hydrogen team and want it, write to us through the app's support link with the layouts you use; the metaobject shapes are stable and we can document them properly for anyone building against them.

Customer photo submissions

The upload form shoppers see, described in the customer upload guide, posts through a Shopify app proxy on your Online Store domain. App proxies are an Online Store feature: Shopify forwards a path on your storefront to the app. A Hydrogen storefront does not have that path unless you add a route that forwards to it, and the form itself is rendered by the block, so in practice customer submissions are an Online Store feature today.

The moderation queue is in the admin and works regardless of where photos came from. If a headless store collected customer photos some other way and added them to a gallery through the admin, the moderation guide applies unchanged, and so do the data request and erasure steps in the GDPR guide.

Partly headless stores

Most stores that go headless do not do it everywhere at once. A common shape is Hydrogen for the home page, collections and products, with the Online Store still serving pages, blogs and policies, because they are edited by people who like the theme editor. In that arrangement Snug Gallery keeps working on every Online Store page exactly as before. A lookbook page or an about page built with the block is unaffected by the Hydrogen rollout as long as it stays on the Online Store channel.

The reverse is worth stating too. If a page moves from the Online Store to Hydrogen, the block on it stops rendering on the day the route switches, with no warning from the app, because nothing about the gallery changed; only the page that used to show it did. Put the galleries on the list of things to check when a route moves, alongside forms and embeds.

Plans and the storefront

Snug Gallery's plan limits are enforced in the admin when you create galleries and upload images, and the block reads the current plan from an app metafield so it can behave accordingly on the storefront. A Hydrogen component reading metaobjects directly does not go through that check, and we do not mind; the limits are about what you can create, and the admin already applied them. What the plan limits guide says about galleries over the limit staying intact applies in full.

The short version for a migration plan

If you are writing the migration checklist, the Snug Gallery line reads like this. Galleries and images: kept, readable through the Storefront API as metaobjects and files. Gallery block and lightbox: Online Store only, needs a React component in Hydrogen. Customer uploads: Online Store only. Admin, moderation, plan: unchanged. Pages that stay on the Online Store: no change at all. That is the whole of it, and it is a more comfortable position than an app that keeps your images on its own servers behind its own script, which is the comparison the third-party script guide draws for the theme case.

Snug Gallery was built for Online Store themes first because that is where most merchants are, and we keep the storefront data in standard Shopify objects precisely so that a decision like going headless is yours to make without asking us.

Frequently asked questions

Does Snug Gallery work with Shopify Hydrogen?

Not as a drop-in. The gallery block is a theme app extension rendered by the Online Store, and Hydrogen does not render Liquid or app blocks. Your galleries are standard metaobjects and files, so a Hydrogen storefront can query them through the Storefront API and render them with its own component, but there is no official Snug Gallery component for Hydrogen today.

Can I read Snug Gallery galleries with the Storefront API?

Yes. Galleries and their images are metaobjects of app-reserved types with storefront read access, the same access the theme block relies on. A Storefront API query for metaobjects of the gallery type returns the title, layout, sort mode and the list of image metaobjects, each with its file reference, alt text, captions, link, hotspots, video URL and tags.

Will my galleries disappear if I move my store to Hydrogen?

No. Nothing is deleted by changing storefront. The galleries stay in your store as metaobjects, the images stay in Files, and the admin app keeps working. What stops is the rendering on any page that moves off the Online Store channel, because the block that drew the gallery no longer has a place to run.

Do customer photo uploads work on a headless storefront?

Not today. The upload form is part of the theme block and submits through a Shopify app proxy on the Online Store domain. A headless store would need its own form and a route that forwards submissions. Moderation in the admin works for any photo that reaches a gallery, however it got there.