logo
Shopify Builds>Primitives>Liquid section schema and settings

Liquid section schema and settings

Definition

A section's schema is a JSON block declaring its name, its settings, its block types and where it's allowed to appear. Shopify renders those settings as theme-editor controls and hands the merchant's values back to the section at render time. It is the contract between the developer who writes a section and the person merchandising it.

Documented at shopify.dev, section schema.

How We've Used It

This is the primitive nearly every build here rests on, because it decides who can change a page after we leave. The habit is to expose the merchandising decision and keep the engineering one in code: which collection, which copy, which order, which promo slot are settings, while the render logic isn't. Block types are what make a section composable, and a product section with two dozen of them is a page a merchant can rebuild without us. That is the argument against a page builder.

Builds Using It

201 further gated builds use it; their pages follow.

Related Entities

Builds

Audience-targeted announcement bar with sticky-height measurement

Dawn's announcement bar, extended so each announcement block carries an audience setting, the section counts the matching blocks before it renders, and that count decides whether the page gets no bar, a static line or a carousel — with slide numbering that matches what's actually on screen, and a pinned height the rest of the layout can read.

LUS Brands

Rotating announcement carousel above the header, with pause control

An auto-rotating promo bar rendered by the layout above the header: a looped Swiper of up to ten text blocks that reserves its height before any script runs, waits for the carousel library on a bounded retry, and gives the shopper a real pause control whose label always says what it will do next.

Nudestix

Arched-label icon grid PDP block

A six-slot row of circular badge icons with captions that curve over them — an SVG `textPath` per label, an arc id composed from `block.id` so the block can repeat, and layout driven entirely by custom properties the merchandiser sets.

LUS Brands

Adults/Kids audience-switching header with automatic menu swap

One Liquid predicate decides which audience a page belongs to. The header reads it, replaces the entire navigation with the kids menu, and keeps a two-button switch back to the adult side in reach on desktop and mobile alike.

LUS Brands

Brand story split panel: one section that renders image, hosted video or YouTube with separate desktop and mobile assets

A 50/50 story panel whose media half is a picture, a Shopify-hosted video or a YouTube embed depending on one select, whose mobile aspect ratio is computed in Liquid from the asset that will actually load, and whose type scale, spacing and side-flip are all settings — so an About page is one section, placed as many times as the story needs.

LUS Brands

A collection template turned into a palette builder that carts one priced SKU

A pick-your-own palette promotion runs on a normal collection page wrapped in a `<bundle-element>` custom element, which holds a fixed tray of empty slots and posts one priced bundle product with the shopper's picks attached as line-item properties.

Nudestix

'Bundle and save' PDP block driven by a product-list metafield

One product-list metafield, one card per product, and on every card a working add-to-cart form of its own — a merchandiser-curated set sold on the product page where the shopper already is, with a carousel that only appears when there is more than one thing to scroll.

LUS Brands

A second product template whose add-to-bag switches between one cart line and several

`main-product-bundle.liquid` is a fork of the theme's product section in which one Liquid conditional wraps the buy form in either a standard `<product-form>` or a `<bundle-product-form>`, depending on which bundle metafield the product carries.

Nudestix

Cart page rebuilt around loyalty points, protected gifts and a dark order summary

Dawn's single-table cart section rewritten as a two-column page: per-line loyalty points computed in Liquid, gift lines a shopper can't edit away, bundle lines that link back to the builder that made them, and a summary panel that survives every re-render.

Nudestix

Threshold-driven free shipping, deluxe sampling and a first-order gift notice

Merchandiser-set spend thresholds evaluated in Liquid on every render of the cart section: free-shipping and deluxe-sampling messaging with a remaining-amount placeholder, a first-order gift notice that can tell a guest from a customer, and a free add-on whose control posts to the Cart AJAX API and asks the server for the section again.

Nudestix

Creator collab video listing driven by article metafields

A blog turned into a creator video index: each article is a creator record whose video address, platform and handle live in article metafields, rendered as a paginated grid of inline-playing cards that request no third-party iframe until someone presses play.

Nudestix

Collection grid card on a licensed theme: metafield merchandising, a badge precedence chain, a hover-swap swatch element and first-row loading hints

Palo Alto's grid item extended so the card's title, strapline, cutline and badge come from product metafields, badges resolve in one fixed order, color options become a swatch element that swaps the card image on hover, and column classes are computed from whatever section happens to be calling.

Three Ships

Collapsible desktop filter sidebar that reflows the product grid instead of squeezing it

Toggling the vertical filter rail switches the collection grid between four columns and three, keeps that choice for the browsing session, and re-applies it every time the facet pipeline replaces the grid wholesale.

LUS Brands

Main collection grid: merchandisable promo tiles, load-more and a filter blocklist

Dawn's collection grid extended in four directions: promo tiles a merchandiser places by grid position, a textarea that suppresses unwanted filter values, load-more over the Section Rendering API, and an infinite-scroll fallback.

Nudestix

Collection page: three filter modes, in-grid promo blocks and infinite scroll

The live collection body here is vendor code from a paid premium theme. This page documents what that code does, how it is configured across a large template set, and where our own contribution to it begins and ends.

Three Ships

Tabbed collection product slider and the shared merchandising card

One section renders every configured collection at once and switches between them with a class, so moving from Serums to Cleansers waits on nothing — and one card snippet backs the shelf, the blog and the rewards page.

Three Ships

Curl Quiz 3.0: a nine-step diagnostic quiz rendered entirely from Shopify metaobjects

A nine-step hair diagnostic on the LUS Brands storefront whose questions, options and selection rules live in Shopify metaobjects rather than in the section's code. The theme editor exposes exactly one setting.

LUS Brands

Marketing image banner with mobile art, typography controls and highlight headings

A campaign banner built as a fork of Dawn's image banner: the vendor's class contract and overlay behaviour left intact, with a real mobile source, per-block type controls and an inline highlight convention layered on top.

LUS Brands

Merchandisable homepage product carousel with a tag-driven badge engine and inline add-to-bag

A two-column row — optional linked lifestyle image, Swiper rail — where every label, color, badge and product is a theme-editor setting, and each card can add to bag without leaving the page.

LUS Brands

DE Hero: art-directed image/video hero with layout controls

A campaign hero that serves a genuinely different mobile crop through hand-built `<picture>` markup, publishes both breakpoints' aspect ratios as CSS custom properties, switches to a hosted video from one setting, can make the whole frame a link, and decides its own loading priority from where it sits on the page.

LUS Brands

Shop-by-category carousel with collection-aware card fallbacks

A homepage category rail where adding a category is one action — pick the collection. The image, the link and the label all resolve from the collection record unless a merchandiser deliberately overrides them.

LUS Brands

Detached mobile drawer with three-level native-details navigation

The mobile menu panel lives outside the element that opens it. The theme's own drawer class was taught that shape, and the panel it opens is a native `<details>` accordion three levels deep that expands without JavaScript.

LUS Brands

Editorial split banner with typographic control and merchandiser-authored offer details

A homepage banner where layout mode, desktop and mobile artwork, subtext type scale, five colours and an offer-details panel are all settings, so a campaign and its terms publish together without a developer in the loop.

Nudestix

Homepage exclusive-offers rail with caption heights equalized in idle time

A merchandiser-built row of promotional tiles for the Nudestix homepage — grid or swipe rail, chosen separately for desktop and mobile — whose uneven caption blocks are measured in idle time and equalized through a single `--content-height` custom property.

Nudestix

Kids FAQ page: single-level variant of the FAQ engine

A second FAQ page for the kids sub-brand that shares the help center's content model — the same page metafield, the same accordion contract — but drops the category layer, so a shorter list of questions reads as one flat, keyboard-operable accordion with its own tone and its own way out.

LUS Brands

Featured-collection product card with metafield hero/hover media and a tag-driven badge stack

The card that renders inside the homepage's main merchandising rail: hero and hover art chosen in the Shopify admin, a responsive image ladder built by hand, and a badge stack resolved from tags, price and block settings at render time.

LUS Brands

Featured tutorial with an adjacent shoppable product rail

One section, two halves: a poster-first video that fetches its YouTube or Vimeo player only on click, and beside it the first three products of whichever collection a merchandiser picks — each one a real card with a quick view and an add to bag that never leaves the page.

Nudestix

Font delivery and a template-conditioned image preload in a licensed theme's layout

Three Ships' `theme.liquid` decides its own font delivery on a licensed theme — the picked faces preloaded, an Adobe Fonts `@font-face` block inlined with its loader demoted behind it — and emits one image preload on exactly one template type, under an explicit condition.

Three Ships

Theme-wide section reveal that replaces Dawn's per-element scroll animations

One entrance animation for every top-level section on the storefront, applied from the layout rather than authored into each section — with the hide decided before first paint, the reveal driven by an intersection observer, and reduced-motion and no-JavaScript visitors never hidden from anything.

LUS Brands

Before/after customer results carousel with an attached product card

One slide per customer result: two labeled photos, a quote with its attribution, and the product that was used — rendered as the storefront's own product card, with the live price and a working add-to-bag, on a page template where Shopify hands the theme no product at all.

Nudestix

Predictive search moved off Shopify onto an external search API with client-side templating

The type-ahead rebuilt from the inside: same custom element, same keyboard model, same ARIA contract — a different data source and a render step that did not exist before.

Nudestix

Metafield-driven two-level FAQ accordion grafted into a help-center app's shell

The help-center page kept the app's shell. The answers inside it moved into a Shopify page metafield, and a two-level accordion we wrote renders them — deep-linkable, keyboard-operable and reusable elsewhere in the theme.

LUS Brands

Hero slide content renderer with per-breakpoint typography controls

One Liquid snippet renders a hero slide's pretitle, title, description and CTA from block settings, carrying the desktop and the mobile type spec on the same element as paired CSS custom properties, so two different slideshow sections share a single copy renderer.

Nudestix

Homepage hero carousel v2 - video and split-image slides with per-slide typography control

The live homepage hero: two independent carousels over one authored slide list, video slides and split-image slides, typography controlled per slide, and promotion events fired from the slide's own copy.

Nudestix

House pagination component with result counter for blog and collection grids

A self-contained `de_pagination` snippet: pill page buttons, prev and next arrows that become non-focusable spans at the ends of the range, and a computed result-range line, rendered by the blog index and the collection grid from one file.

LUS Brands

Four selectable How-To step layouts from a single metaobject step list

One list of `how_to_use` step metaobjects renders as a card grid, a slider, a numbered timeline or an image-and-text split, chosen per product, with a desktop and a mobile asset per step and video that plays only while in view.

LUS Brands

A-Z ingredient glossary with scroll-spy letter navigation and product cross-sell

An ingredient encyclopedia authored as theme-editor blocks across 14 section instances on one page template, joined to a sticky letter bar by a single shared attribute, with every entry an accordion that links out to the products it appears in — education page as cross-sell surface.

Three Ships

Kids featured collection: a custom element that builds its Swiper on approach and wraps the theme's own product cards

A `<kids-featured-collection>` element leaves its slides as static markup until an IntersectionObserver fires, initializes Swiper then, and tears everything down when the section is removed — around Dawn's `card-product`, not a card of its own.

LUS Brands

Landing-page hero sections with a no-JS add-to-cart on page templates

A hero kit for standalone campaign pages: per-breakpoint artwork and text placement in repeatable blocks, and a CTA that can be a real Liquid product form on a template where Shopify hands the theme no product at all.

Three Ships

Layout shell rewritten as a load-order contract: origin hints, two stylesheet tiers and an interaction-gated session recorder

Dawn 6.0.2's `theme.liquid` reworked so that the order things load in is written down: connection hints before the title, stylesheets sorted into a blocking tier and a deferred tier, fonts preloaded, and a session-recording script that waits for the shopper to move.

Nudestix

Press / trust logo strip with scroll-snap carousel and no JavaScript

A blocks-based logo row for the homepage that a merchandiser can reorder, relabel and link — and that becomes a swipeable, snapping carousel on mobile through CSS alone, with no slider library and no script of its own.

LUS Brands

Mega-menu header with separate mobile menu and image blocks

A second link-list setting gives the mobile drawer its own information architecture, and section blocks put imagery into panels that Shopify's link lists have no way to carry it in.

Three Ships

Title-matched mega menu with a full-depth link-list fallback

Shopify gives a navigation item no settings of its own. This menu joins each top-level link to a theme-editor block by matching their titles, and renders a full link-list panel for every item that has no block behind it.

Nudestix

Per-collection hero banner driven entirely by collection metafields

One section instance in the collection template serves every collection: its heading, copy and two separately cropped artworks are bound to collection metafields through dynamic sources, and it renders two independent breakpoint layouts from them, so launching a collection is a merchandising task rather than a theme edit.

LUS Brands

Tabbed mobile Shop menu with featured banner panel

A custom `<shop-tabs>` element turns the drawer's first-level Shop menu into horizontal tabs with panels of category links, merges a theme-editor banner block into the tab order by position, and leaves every other drawer item on the vendor's accordion.

Three Ships

Rebuilt 2026 PDP section with merchandiser-composable blocks and per-product ATC color

A custom product section for LUS Brands that declares 26 block types beyond Dawn's set, resolves title and subtitle copy per variant, and paints the add-to-cart button from a product metafield.

LUS Brands

Configurable PDP block system on the Palo Alto theme (Recharge widget placement, size charts, siblings, quick view)

Merchandiser-orderable buy-box blocks on Three Ships' licensed theme, with the subscription app block captured and re-emitted inside the buy box, plus metafield-driven size charts, a product-family switcher and a sticky add-to-cart bar.

Three Ships

"Save With Sets": shade-selectable kit contents on the component product's page

A metafield-linked list of kits renders as an accordion on the product pages of the products inside them, and each kit opens a modal where every component gets its own shade picker before a single add-to-bag.

Nudestix

PDP content accordion that borrows the premium theme's collapsible contract

A product-page accordion block that reuses Palo Alto's own `data-collapsible-*` behavior wiring while supplying its own heading semantics, CSS-variable theming and a responsive table layout for the long-form panels merchandisers author per product.

Three Ships

Product-page FAQ accordion: page-backed answers, mobile 'View More' reveal, auto-emitted FAQPage

A local extension of Palo Alto's Tabs section that hides every FAQ row past the third on mobile behind one reveal button, and emits `FAQPage` JSON-LD from the vendor's own block loop, reading each answer from the same Shopify page or rich-text field the accordion displays.

Three Ships

Variant-aware PDP hero banner driven by a 'heroic' metaobject

An editorial hero below the buy box that resolves its art, headline and copy from a per-variant metaobject, and refetches its own content through the Section Rendering API when the shopper switches variant.

LUS Brands

Metafield-driven PDP content system: auto-built accordions, need-to-know strip and campaign widgets

A layered content resolver on the Nudestix product page: legacy description HTML parsed into accordions at render time, three of them overridden per shade from metafields, with icon strips, badges and campaign widgets assembled from 29 metafield keys around them.

Nudestix

On-model shade carousel bound two ways to the Dawn variant picker

A Flickity carousel of one on-model shot per shade, rendered below the product gallery from a variant metafield; each cell carries the id of its Dawn variant radio, a tap on a face resolves to a click on that radio, a click on a radio moves the carousel — and the carousel itself never touches the product form.

Nudestix

Grouped shade swatch picker with shade-finder dialog and GA4 shade-finder events

Finish became a variant metafield instead of a second product option, which is what lets forty shades group into Matte, Matte Lux and Bloom without touching the SKU matrix — and the shade quiz beside them is bought, wrapped in a native dialog and measured on our side of the boundary.

Nudestix

Product card with award badges, per-variant content payload and per-card structured data

One snippet renders the whole Nudestix grid card: tag and award badges, quick view, wishlist, comparison, an in-grid add to bag, and a per-variant data payload the shade switcher reads without a fetch.

Nudestix

Side-by-side product comparison drawer and modal table

A compare-products flow with no app behind it: card checkboxes write the selection to localStorage, a drawer pinned to the bottom of the viewport carries it from collection to product page and back, and the modal table fetches each product's long-form copy from that product's own page section at the moment the shopper asks to compare.

Nudestix

Metafield-driven product information tabs with mobile accordion and variant refresh

How To, Ingredients, FAQs and Tips render below the buy box from metafields — as tabs on desktop, as a native accordion on mobile, and re-resolved from the server every time a shopper picks a different variant.

LUS Brands

Quiz results: a 34-rule, priority-ordered recommendation engine running client-side from metaobject data

The half of the Curl Quiz that turns answers into products. Liquid renders every possible recommendation once into hidden templates; a matcher in the browser runs 34 priority-ordered rules and clones the survivors into three result groups.

LUS Brands

Rich-text section rebuilt as a per-block typography and highlight system

Dawn's `rich-text.liquid`, kept under its own name and rebuilt inside: every heading, text and button block writes its own type, spacing and colour tokens as CSS custom properties, and the `[[word]]` highlight and the button become snippets other sections share.

LUS Brands

Filter-triggered promo cards inside the search results grid

A theme-editor block that puts a merchandiser-designed card into the search results grid at a chosen position, and shows it only while a named facet is active on that query.

Three Ships

Color-accurate shade swatches driven by a merchandiser-editable hex registry

Roughly 250 `Shade Name:#hex` pairs live in one theme setting. The product section resolves every option value against them in Liquid, groups the results by finish, and paints each swatch server-side.

Nudestix

Themed host section for Shopify Forms app blocks

A section whose only block type is `@app`, wrapping any app block in the theme's width, padding and background scaffolding — and, when a merchandiser switches it on, writing the `--forms-heading-*` and `--forms-body-*` custom properties that Shopify's Forms embed reads for its own typography.

Three Ships

Skin quiz entry-point sections: separate desktop and mobile artwork in one section

A campaign panel that opens the Three Ships skin quiz, built so the desktop and mobile crops are two independently chosen images and the copy above them is four editable blocks.

Three Ships

"Start with the basics" — a merchandiser-authored 3-step routine section with measured read-more clamping

A homepage routine band whose three step cards are theme-editor blocks tied to real products, whose heading takes a `[[...]]` highlight token, and whose "Read more" button is unhidden only after the browser has measured that the copy overflows its four-line clamp.

LUS Brands

Subscription bundle grid with tiered unlock progress

Two custom elements on the subscription landing page: a card whose two-step button reveals a frequency choice and then posts the variant with that `selling_plan` to the cart, and a wrapper that fetches the live cart after every add and drives a merchandiser-defined tier bar from what it finds there.

Three Ships

Metafield-driven editorial article template (TSB blog)

A long-form article template assembled entirely from article metafields — deck, takeaways, science callouts, references, FAQ, author credentials, related reading and in-content commerce — in a single section with no theme-editor settings, so an editor never touches the theme to publish a fully structured post.

Three Ships

Inline size picker on cart and PDP upsell cards

Size pills added inside the premium theme's own upsell card, so a multi-variant upsell in the cart drawer, on the cart page or in a product-page "pair with" module can be sized and added where it stands instead of sending the shopper somewhere else.

Three Ships

Variant-aware price snippet with percentage + value savings badge

Dawn's price snippet extended so a caller can hand it any variant object ahead of the snippet's own lookup, and so a savings badge — a percentage computed in Liquid plus a merchandiser-written value sentence — renders whenever the compare-at price is higher than the price.

LUS Brands

Shade swatch rendering and per-variant content payload

The swatches are the visible half. The other half is a hidden input per variant carrying that shade's copy, ingredients, SEO fields and badges — a data contract three separate features read without asking the server anything.

Nudestix

Shade-level collection grid hydrated from an external faceting service

A Shopify collection template that lists shades instead of products: the section renders an empty grid shell, then builds every card, facet and count in the browser from a bespoke faceting service outside the theme.

Nudestix

Alt-text convention that maps product media to variants without metafields

Two Liquid snippets turn the alt text merchandisers already type in the Shopify media library into a variant match key and a four-tier match verdict, so a product gallery can filter media per variant at render time.

LUS Brands

Pill variant picker with merchandiser-named size labels

Dawn prints an option value and nothing else. We extended its picker so a size pill carries two lines — a merchandiser's word for that size above the size itself — and falls back to positional defaults when nobody has written one.

LUS Brands

Vertical filter rail and an in-place mobile filter accordion replacing Dawn's drill-down drawer

Dawn's facets snippet was rebuilt into a sidebar rail with color swatches and show-more truncation, an accordion mobile drawer where every group opens in place, and a single sort control that physically relocates between breakpoints.

LUS Brands

Responsive video hero with independent desktop/mobile sources and single-source-of-truth playback controls

A `<video-hero>` custom element that holds a 16:9 cut and a 9:16 cut, promotes only the active breakpoint's sources to `src`, and wires one play/pause and one mute button to whichever video is live — with server-rendered control state so the buttons read correctly before the script runs.

LUS Brands

Accessible play/pause web component for autoplaying hero video

A `<play-pause>` custom element that gives a muted, autoplaying hero video a real keyboard-reachable control — self-wiring from a selector in its own markup, so Swiper can clone and reorder slides without any script knowing how many there are.

Nudestix

Eight WebMCP tools that make a product page answerable — and buyable — by a browser agent

A feature-detected block in the theme layout registers eight `navigator.modelContext` tools on one trial-kit product page — seven an agent can read from, one that adds a Liquid-fixed variant to the cart.

Three Ships