Theme reference
Generated from the validator's own rules, so it cannot drift from what we accept. Point your editor at the JSON Schema and you get all of this as you type.
Nodes
What you can draw. A section's `render` is a list of these.
| box | A container. Becomes a div, or any layout or landmark tag you name. |
| text | A line of text, in the tag you name: a heading, a paragraph, a label. |
| rich | Richtext a merchant wrote, sanitised every time it is drawn. |
| img | A picture, drawn at the width its role says it will be drawn at. |
| link | An anchor around anything. |
| each | Repeats its children over a list, under a limit it does not choose. |
| if | Draws one set of children or another, on a condition. |
| slot | Repeats its children once per repeatable block, with `block` in scope. |
| icon | One of the storefront's own icons. |
| money | An amount, formatted in the shop's display currency. |
| component | One of the components below. The only interactive thing a theme can place. |
Components
The interactive parts. You place and position them; you cannot write one. Those marked with slots take their layout from your theme.
| product-card | A product in a grid: picture, title, price, and quick add. |
| add-to-cart | The button, with a quantity field in front of it. Pass `quantity: false` for a one-press add. |
| variant-picker | Size, colour and the rest, wired to what is in stock. |
| search-box | The search field and its suggestions. |
| newsletter-form | Email capture, with the shop's own consent wording. |
| cart-drawer | The basket that slides in when something is added. |
| pagination | Next and previous, for a listing that runs past one page. |
| price | An amount with its compare-at and its currency handled. |
| account-menu | Sign in, or the customer's own links when they are. |
| accordion | Rows that open. You lay out the title and the body; a merchant adds the rows. Slots: title (per block), body (per block). |
| image-carousel | Slides the shopper can move through. You lay out one slide. Slots: item (per block). |
| popup-panel | Something that opens when pressed. You lay out the button and the panel. Slots: trigger, content. |
| shop-logo | The shop's own logo, at the size it was uploaded. |
| shop-menu | A menu the merchant built, resolved to real links. |
| cart-link | The basket, and how many things are in it. |
| currency-switcher | The currencies this shop actually sells in. |
| language-switcher | The languages this shop is published in. |
| social-links | The shop's own accounts, as icons. |
Data
A section declares what it needs and the page fetches it before drawing anything, so two sections asking for the same list cost one query. A theme cannot write a query of its own.
| newest-products | The most recently added products in the shop. |
| collection-products | Products in a category, or the newest if none is chosen. |
| collections | The shop's categories. |
| product-variants | The variants of the product on this page. |
| product-images | The pictures of the product on this page. |
| related-products | Products that go with the one on this page. |
| metaobjects | Entries of a custom content type your theme defines. |
| cart-lines | What is in the basket right now. |
| menu | A named menu the merchant built. |
Design tokens
Your theme.json sets the defaults; the merchant can change any of them. Read them in CSS as the custom property beside each one.
| colorBg | Page background. CSS: var(--shop-bg). Default: #ffffff |
| colorFg | Text. CSS: var(--shop-fg). Default: #0f1115 |
| colorAccent | Accent. CSS: var(--shop-accent). Default: #7c3aed |
| colorMuted | Muted text. CSS: var(--shop-muted). Default: #6b7280 |
| fontHeading | Heading font. CSS: var(--shop-font-heading). Default: "Inter", system-ui, sans-serif |
| fontBody | Body font. CSS: var(--shop-font-body). Default: "Inter", system-ui, sans-serif |
| fontSizeBody | Body text size. CSS: var(--shop-font-size-body). Default: 16px |
| fontSizeHeading | Largest heading size. CSS: var(--shop-font-size-heading). Default: 60px |
| radius | Corner radius. CSS: var(--shop-radius). Default: 0 |
| maxWidth | Content width. CSS: var(--shop-max-width). Default: 1200px |
| controlRadius | Button and field radius. CSS: var(--shop-control-radius). Default: 0 |
| btnBg | Button background. CSS: var(--shop-btn-bg). Default: #000 |
| btnFg | Button text. CSS: var(--shop-btn-fg). Default: #fff |
| btnBorder | Button border. CSS: var(--shop-btn-border). Default: #000 |
| imageMain | Main image, desktop. CSS: var(--shop-img-main). Default: 50vw |
| imageMainMobile | Main image, mobile. CSS: var(--shop-img-main-mobile). Default: 100vw |
| imageSmall | Grid image, desktop. CSS: var(--shop-img-small). Default: 25vw |
| imageSmallMobile | Grid image, mobile. CSS: var(--shop-img-small-mobile). Default: 50vw |
| imageThumbnail | Thumbnail, desktop. CSS: var(--shop-img-thumbnail). Default: 96px |
| imageThumbnailMobile | Thumbnail, mobile. CSS: var(--shop-img-thumbnail-mobile). Default: 72px |
| imageSwatch | Swatch, desktop. CSS: var(--shop-img-swatch). Default: 48px |
| imageSwatchMobile | Swatch, mobile. CSS: var(--shop-img-swatch-mobile). Default: 40px |
| checkoutSummarySide | Order summary on the. CSS: var(--shop-checkout-direction). Default: row |
| checkoutSummaryBg | Summary background. CSS: var(--shop-checkout-summary-bg). Default: #F3F7FF |
| checkoutSummaryFg | Summary text. CSS: var(--shop-checkout-summary-fg). Default: #000000 |
| checkoutFontHeading | Checkout heading font. CSS: var(--shop-checkout-font-heading). Default: ui-sans-serif, system-ui, -apple-system, "Segoe UI", Roboto, sans-serif |
| checkoutHeadingSize | Checkout heading size. CSS: var(--shop-checkout-heading-size). Default: 24px |
Expression roots
Where a `get` path may start. Which of these are in scope depends on where you are: `block` inside a slot, `item` (or whatever you named it) inside an each.
settings · theme · block · shop · page · product · collection · cart · customer · data
Tags
What a box and a text node may become.
box
div · section · header · footer · nav · main · aside · article · ul · ol · li · figure · figcaption
text
p · h1 · h2 · h3 · h4 · h5 · h6 · span · strong · em · small · blockquote · label
Icons
The storefront's own set. An icon node names one of these.
search · account · bag · bin · menu · close · chevron · clock · trend · folder · instagram · facebook · x · tiktok · youtube · pinterest · linkedin
Limits
Ceilings, all of them boring. A bundle is read on every request, so its size is a speed budget as much as a safety one.
| sectionsPerBundle | 60 |
| fieldsPerSection | 40 |
| blocksPerSection | 12 |
| fieldsPerBlock | 20 |
| templateSections | 40 |
| metaobjectTypes | 40 |
| fieldsPerMetaobject | 30 |
| cssBytes | 200,000 |
| sectionCssBytes | 40,000 |
| bundleBytes | 2,000,000 |
| dataRequestsPerSection | 6 |
| customSections | 30 |
| customSectionBytes | 60,000 |