Custom CSS for a Shopify gallery block, safely scoped

Most gallery styling questions are small. The caption font should match the theme's headings. The gap between tiles should be tighter on phones. The carousel arrows should be white on this dark page. A gallery block with thirty settings still cannot anticipate every one of those, and the usual answers, editing the theme's stylesheet or pasting rules into the theme's global custom CSS box, both reach further than the problem. Snug Gallery has a Custom CSS box on the gallery block itself. This guide explains exactly what it does with the text you type, which class names and variables are there to be targeted, a handful of examples that cover the common requests, and the two places a block-scoped rule cannot reach.

What the box does with what you type

The setting is a text area called Custom CSS, near the bottom of the gallery block's settings in the theme editor, with a one-line example next to it. It is available on every plan, including Free, and it is a block setting, so it belongs to one placement of the gallery: the same gallery dropped onto a product page and a lookbook page can carry different rules in each place, and duplicating the section in the theme editor copies the rules along with the other settings.

When the page renders, the block writes a small style element and wraps your text in a selector that is unique to that block, built from the block's own identifier. If you type `.snug__img { filter: sepia(1); }`, what the browser receives is that rule nested inside `#snug-<block id> { ... }`, so it only matches images inside this one gallery. Nothing you type can leak out to the header, the product form or another gallery on the same page. The wrapper relies on native CSS nesting, which every current browser has supported since 2023; an old browser that does not understand nesting ignores the block and shows the gallery with its default styling, which is the right failure.

One character is removed before output: the less-than sign. That is the character that could close the style element and start injecting markup into the page, so the block strips it. Valid CSS never needs it, and the strip is why a text field in the theme editor is safe to expose to anyone with theme-editing access. Everything else goes through as written, including comments, which is a reasonable place to leave yourself a note about why a rule exists.

Two kinds of rule, and where each goes

Because the text is nested inside the block's selector, there are two ways to write a rule. Bare declarations with no selector apply to the gallery's outer wrapper itself. `padding: 24px; background: #f6f1ea;` gives this one gallery a tinted panel with breathing room. Declarations with a selector apply to things inside the wrapper: `.snug__caption-title { text-transform: uppercase; }` changes caption titles in this gallery and nowhere else.

The bare form is also how you override the block's own layout variables. Every gallery sets a handful of custom properties on its wrapper from the settings you chose: the number of columns, the gap between tiles, the corner radius, the aspect ratio, the border and shadow, the caption colours and the pin colour for shop-the-look markers. Writing `--snug-gap: 4px;` at the top level of the box replaces the gap from the slider. The variables are listed below, and because they feed the same rules the block already uses, changing one is less likely to fight the layout than writing new rules against the tiles directly.

Media queries work inside the nesting too, so a rule for phones only is `@media (max-width: 749px) { --snug-gap: 2px; .snug__caption { font-size: 12px; } }`. The block itself switches columns at 750 and 990 pixels, which are good breakpoints to reuse so your rules change at the same moments the layout does.

The names worth knowing

The gallery's markup uses one naming scheme throughout, a block name followed by two underscores and the part. The wrapper is `.snug`, and it also carries modifier classes that say which layout and options are active, such as `.snug--masonry`, `.snug--carousel`, `.snug--captions-hover` or `.snug--hover-zoom`, which lets a rule depend on a setting without repeating it. Inside, `.snug__heading` is the optional heading above the tiles, `.snug__filters` and `.snug__filter` are the tag filter bar and its buttons, and `.snug__grid` holds the tiles.

Each tile is `.snug__item`, containing a `.snug__figure` with the `.snug__img` image or `.snug__video`, and a `.snug__caption` whose placement is one of `.snug__caption--below`, `.snug__caption--overlay` or `.snug__caption--aside`, with `.snug__caption-title` and `.snug__caption-text` inside. Images that link somewhere are wrapped in `.snug__link`. Carousel and slider layouts add `.snug__arrow` with `--prev` and `--next` variants, and `.snug__dots` with `.snug__dot` children. Shop-the-look markers are `.snug__pin`, `.snug__hotspot` and `.snug__hotspot-label`, and a tile's video play button is `.snug__play`.

The variables set on the wrapper are `--snug-cols`, `--snug-gap`, `--snug-radius`, `--snug-ratio`, `--snug-border`, `--snug-shadow`, `--snug-caption-bg`, `--snug-caption-color` and `--snug-pin`, with `--snug-big` and `--snug-tile-ratio` added for the collage layout. These are the names the block renders today. They have been stable across the layouts described in gallery layouts compared, and the app treats them as part of what merchants rely on, but a stylesheet written against them should be checked after a major update like any other customisation.

Six requests and the rules that answer them

Match the theme's heading font on captions. Themes expose their fonts as variables; Dawn and the themes built on it use `--font-heading-family`. So: `.snug__caption-title { font-family: var(--font-heading-family); letter-spacing: 0.04em; }`. If your theme uses a different variable name, the theme's own stylesheet will show it, or name the font directly.

Tighter tiles on phones, roomier on desktop. `--snug-gap: 3px; @media (min-width: 990px) { --snug-gap: 16px; }`. Because the gap is a variable the layout already reads, masonry and grid both respond without any further rules.

White arrows on a dark page. `.snug__arrow { background: #fff; color: #111; } .snug__dot { background: rgba(255,255,255,.5); }`. The arrows are buttons, so keep their size; changing only colour preserves the hit area for touch.

A quieter hover. The Hover effect setting offers zoom, lift, shine and grayscale; if you want colour images that lose saturation until hovered instead, pick None in the setting and write `.snug__img { filter: saturate(.6); transition: filter .3s; } .snug__item:hover .snug__img { filter: none; }`.

Captions that read as labels. `.snug__caption--below { text-align: center; font-size: 13px; } .snug__caption-text { display: none; }` keeps the title and hides the longer caption text on this placement only, which is handy when the same gallery appears in full on its own page and as a strip on the home page.

A brand colour for shop-the-look pins. The block has a pin colour setting, but if you want it to follow a theme variable rather than a fixed hex, `--snug-pin: var(--color-accent, #c8102e);` at the top level does it.

What a block-scoped rule cannot reach

Two parts of the gallery live outside the block's wrapper, and that is deliberate. The lightbox, the full-screen viewer that opens when a shopper taps an image, is created once per page and attached to the end of the document so that it sits above everything and is shared by every gallery on the page. The same is true of the product card that opens from a shop-the-look pin. Neither is inside `#snug-<block id>`, so rules in the Custom CSS box do not apply to them. Their class names begin with `.snug-lightbox` and `.snug-card`, and if you need to restyle them the place to do it is your theme's global custom CSS, where a rule like `.snug-lightbox__caption { font-size: 14px; }` will match.

The second limit is the obvious one: this is CSS, not a template editor. You can hide, recolour, resize and reposition what the block renders; you cannot add elements, change the order of tiles or alter the text. Sort order has its own setting, described in gallery sort order, and captions and alt text are edited in the app. If a request needs new markup, it is a feature request rather than a styling one, and the support address is the right place for it.

A last note on specificity. Because every rule is prefixed with an ID selector, your rules outrank the block's own stylesheet and the theme's, both of which use class selectors. That means `!important` is almost never needed, and if you find yourself reaching for it, the more likely explanation is a typo in the class name. The theme editor shows the result live as you type, so the loop is short: write the rule, look at the preview, adjust.

Why a box on the block rather than a theme edit

The alternatives both have a cost that only shows up later. Editing the theme's stylesheet means the rules live in a theme file; when you switch or update the theme, they are gone, and nobody remembers that the gallery used to look different until a customer mentions it. Pasting into the theme's global custom CSS keeps the rules through theme updates, but they apply to every gallery on every page, and they stay behind if the app is ever removed, which is the kind of leftover that a gallery app that stopped working describes.

Rules in the block's Custom CSS box are stored as a setting of the block, inside the theme's JSON templates, like the column count or the corner radius. They move with the block if you move it, they are removed with the block if you delete it, and they cannot affect anything the block does not render. For small, placement-specific styling that is the right size of tool. Snug Gallery exposes the names and the variables so the box is useful, and scopes the output so a typo in it is a cosmetic problem rather than a page-wide one.

Frequently asked questions

Does the Custom CSS setting affect the whole store or just one gallery?

Just the one gallery block it is set on. The block wraps your rules in a selector built from its own identifier, so they match only elements inside that placement. Another gallery on the same page, or the same gallery on another template, is unaffected unless you add the rules there too.

Is Custom CSS available on the Free plan?

Yes. It is one of the block settings that works on every plan. The settings that depend on a paid plan, such as the Pinterest button, right-click protection and customer photos, are marked as such in the theme editor; Custom CSS is not among them.

Why does my rule for the lightbox not work?

The lightbox and the shop-the-look product card are attached to the end of the page, outside the gallery block, so block-scoped rules cannot reach them. Put rules for those parts, whose class names begin with .snug-lightbox and .snug-card, in your theme's global custom CSS instead.

Can I change the gap or columns with Custom CSS instead of the sliders?

Yes. Write the variable as a bare declaration with no selector, for example --snug-gap: 4px; or inside a media query for one screen size. The block's layout reads those variables, so overriding them is the least disruptive way to change spacing, radius, caption colours or the pin colour.