Skip to content

Theme code lets developers and agencies add their own sections, blocks, and snippets to an online store theme. You write them in a Liquid-style template language, and store owners then use them in the store builder like built-in sections, with the settings your {% schema %} declares.

Most developers work from the repzo CLI with an AI tool: repzo store pull downloads the theme as a folder, and you edit it in your own editor. Quick fixes can also be made in the builder’s Code view.

The full list of objects, filters, and tags is in the theme code reference.

repzo store pull writes one theme of a site as a folder:

Path Holds
AGENTS.md The theme code guide: format, objects, filters, tags, behaviours, limits, and examples. AI tools read it before writing code.
sections/<name>.liquid A custom section: template, optional {% stylesheet %}, and {% schema %}. Its type is custom:<name>.
blocks/<name>.liquid A custom block with the same parts. Its type is custom:<name>, used inside sections whose schema accepts it.
snippets/<name>.liquid A reusable piece of template, drawn with {% render '<name>' %}. No schema.
templates/<page>.json One page each: index.json (home), product.json, collection.json, page.about.json, and so on.
sections/header-group.json, sections/footer-group.json The header and footer that every page shares: { "sections": [...] }.
config/settings.json Theme settings (colors, color schemes, fonts, logo, social links), read in templates as settings.<id>.
config/theme.json The theme’s other parts: customCss and embeds (WhatsApp button, chat, pixels).
locales/<lang>.json The store’s built-in words, one file per language ({"add_to_cart": "Add to bag"}). Read them with {{ 'add_to_cart' | t }}.
.repzo-store.json The site, the theme, and the revision you pulled. Don’t edit it.

Code file names use lowercase a-z, 0-9, -, and _ (up to 60 characters) and end in .liquid. The code files are stored inside the theme, so they are versioned and published with it.

A page template looks like this:

{
"kind": "page",
"handle": "about",
"title": { "en": "About us", "ar": "من نحن" },
"document": { "sections": [] }
}
Terminal window
repzo store pull SITE_ID --dir store # download the theme as a folder
repzo store dev --dir store # watch: check and push every save, print a preview link
repzo store push --dir store --dry-run # check everything and see the diff
repzo store push --dir store --yes # save to the draft
repzo store publish SITE_ID --data '{"revision": 12}' --yes # go live

Pushing changes the theme’s draft only. Shoppers see nothing until the theme is published from the builder, the CLI, or the API. See Build a store from the CLI for every command.

Add the section to a template’s document.sections, or to a header or footer group, by its type. Settings are keyed by id:

{ "type": "custom:staff-picks", "settings": { "heading": { "en": "Staff picks", "ar": "اختياراتنا" }, "visible": 4 } }

Leave id out for new sections and blocks, and the server gives them one. Keep the ids of existing ones.

You can also add it with repzo store sections add SITE_ID --data '{"type":"custom:staff-picks"}' --yes. In the builder, store owners find it under Add section → Custom, built from the section’s presets.

A section file has three parts: the template, an optional {% stylesheet %}, and one {% schema %}.

<div class="banner">
{% if section.settings.image %}{{ section.settings.image | image_tag: class: 'banner__image', loading: 'eager' }}{% endif %}
<div class="banner__text">
<h2>{{ section.settings.heading }}</h2>
{% if section.settings.link != blank %}<a class="banner__button" href="{{ section.settings.link }}">{{ section.settings.button_label }}</a>{% endif %}
</div>
<div class="banner__features">{% content_for 'blocks' %}</div>
</div>
{% stylesheet %}
.banner { position: relative; display: grid; gap: 2rem; padding: 4rem 1.5rem; text-align: center; }
.banner__image { width: 100%; max-height: 32rem; object-fit: cover; border-radius: var(--sf-card-radius); }
.banner h2 { font-family: var(--sf-font-heading); font-size: calc(2.5rem * var(--sf-heading-scale)); }
.banner__button { display: inline-block; margin-top: 1rem; padding: .75rem 1.5rem; border-radius: var(--sf-button-radius); background: var(--sf-btn); color: var(--sf-btn-fg); }
.banner__features { display: grid; gap: 1rem; grid-template-columns: repeat(auto-fit, minmax(12rem, 1fr)); }
{% endstylesheet %}
{% schema %}
{
"name": "Banner",
"settings": [
{ "type": "image_picker", "id": "image", "label": "Image" },
{ "type": "text", "id": "heading", "label": "Heading", "default": "Made for you" },
{ "type": "text", "id": "button_label", "label": "Button label", "default": "Shop now" },
{ "type": "url", "id": "link", "label": "Button link", "default": "/collections/all" }
],
"blocks": [{ "type": "@theme" }],
"max_blocks": 6,
"presets": [{ "name": "Banner" }]
}
{% endschema %}
  • Template: HTML with {{ output }} and {% tags %}. The section’s own values are section.settings.<id>, and its blocks are section.blocks.
  • {% stylesheet %}: CSS scoped to this section, up to 16 KB. Snippets can’t have one.
  • {% schema %}: JSON describing the settings, blocks, and presets. See below.

Inside {% stylesheet %}, use the theme’s CSS variables so your section follows the store’s look:

Variable Holds
--sf-bg, --sf-fg, --sf-accent The section’s color scheme: background, text, accent
--sf-btn, --sf-btn-fg Button background and text
--sf-font-heading, --sf-font-body The theme’s fonts
--sf-card-radius, --sf-button-radius Corner radius of cards and buttons
--sf-heading-scale Heading size multiplier
--sf-page-width The page width

Arabic pages are right-to-left. Use logical CSS such as margin-inline-start, text-align: start, and inset-inline-end instead of left and right.

{% schema %} holds one JSON object per file:

Key Meaning
name Shown in the builder. Text, or {"en": "…", "ar": "…"}.
settings Up to 60 settings: { "type", "id", "label", "default"?, "info"?, … }. Ids use letters, digits, _, or -.
blocks What the section accepts (see Blocks).
max_blocks How many blocks at most (up to 50).
presets [{ "name", "settings"?, "blocks"? }]: what Add section inserts. Without presets, a section can still be added by type.
enabled_on, disabled_on Where it can be used: { "templates": ["product", "collection"], "groups": ["header", "footer"] }.
tag, class The wrapper element and its extra classes.

Template names in enabled_on and disabled_on follow Shopify: index, product, collection, list-collections, cart, search, 404, password, blog, article, page, gift_card, and metaobject (content entry pages).

Text defaults can have one value per language: "default": {"en": "Shop now", "ar": "تسوق الآن"}. When the store has English and Arabic, give every text setting both values, and give fixed words in templates an Arabic version with | t: ar: '…'.

Type In the builder What the template gets
text One line of text (English + Arabic). Text in the page’s language.
textarea Several lines (English + Arabic). Text in the page’s language (use newline_to_br).
richtext Paragraphs (English + Arabic). HTML paragraphs (<p>…</p>).
inline_richtext One line of text. Text.
html Merchant HTML (sanitized when drawn). HTML.
image_picker An image from the media library (also image). Image object (url, alt; prints its URL) or nil.
url A link (site path, https, mailto, tel). Text.
video_url A video link. Text.
color A color (#rrggbb). Text.
range A slider: min, max, step, unit, and a required default. Number.
number A number (min, max, step optional). Number.
select A dropdown: options: [{ value, label }]. The chosen value.
radio Buttons: options: [{ value, label }]. The chosen value.
text_alignment left / center / right. The chosen value.
checkbox On / off. true or false.
product One product. Product object or nil.
product_list Products (limit up to 12). List of product objects.
collection One collection. Collection object with its first 24 products, or nil.
collection_list Collections (limit up to 12). List of collection objects (without products).
blog A blog. { title, handle, articles } with its latest 12 posts.
link_list A navigation menu. Menu object (title, links) or nil.
datetime A date and time (also date). ISO text (use date, or data-sf-countdown).
color_scheme One of the theme’s color schemes. When the setting id is color_scheme, the section’s background and text follow it. Scheme id (scheme-1…).
phone A phone number (E.164). Text.
header A heading in the settings panel. —
paragraph A note in the settings panel. —

A section’s blocks list says what it accepts:

Entry Accepts
{ "type": "@theme" } Every block file in the theme, and every builder block: heading, text, button, image, product card, buy buttons, group, and more.
{ "type": "feature" } The block file blocks/feature.liquid.
{ "type": "heading" } One builder block type.
{ "type": "quote", "name": "Quote", "settings": [...] } An inline block that the section’s own template draws.

A block file has its own template, CSS, and schema. The section draws its blocks with {% content_for 'blocks' %} (all of them, in order) or with {% render_block block %} inside a loop.

<div class="feature">
{% if block.settings.icon %}{{ block.settings.icon | image_tag: class: 'feature__icon' }}{% endif %}
<h3>{{ block.settings.title }}</h3>
<p>{{ block.settings.text | newline_to_br }}</p>
</div>
{% stylesheet %}
.feature { padding: 1.25rem; border-radius: var(--sf-card-radius); background: color-mix(in srgb, var(--sf-fg) 5%, transparent); }
.feature__icon { width: 2.5rem; height: 2.5rem; object-fit: contain; }
.feature h3 { margin: .5rem 0 .25rem; font-family: var(--sf-font-heading); }
{% endstylesheet %}
{% schema %}
{
"name": "Feature",
"settings": [
{ "type": "image_picker", "id": "icon", "label": "Icon" },
{ "type": "text", "id": "title", "label": "Title", "default": { "en": "Fast delivery", "ar": "توصيل سريع" } },
{ "type": "textarea", "id": "text", "label": "Text" }
],
"presets": [{ "name": "Feature" }]
}
{% endschema %}

Your block files also go into the store’s own sections that accept any block, such as Section and Group.

An inline block is declared in the section’s schema and drawn by the section’s own template. Put {{ block.sf_attributes }} on its outer element so store owners can select it in the builder:

<div class="quotes" data-sf-carousel data-sf-autoplay="{{ section.settings.autoplay_ms }}">
<div class="quotes__track" data-sf-track>
{% for block in section.blocks %}
{% case block.type %}
{% when 'quote' %}
<figure class="quotes__slide" data-sf-slide {{ block.sf_attributes }}>
<blockquote>{{ block.settings.text }}</blockquote>
<figcaption>{{ block.settings.author }}</figcaption>
</figure>
{% endcase %}
{% endfor %}
</div>
<button data-sf-prev aria-label="{{ 'Previous' | t: ar: 'السابق' }}">‹</button>
<button data-sf-next aria-label="{{ 'Next' | t: ar: 'التالي' }}">›</button>
<div data-sf-dots></div>
</div>
{% schema %}
{
"name": "Customer quotes",
"settings": [
{ "type": "range", "id": "autoplay_ms", "label": "Autoplay (ms, 0 = off)", "min": 0, "max": 10000, "step": 500, "default": 5000 }
],
"blocks": [
{
"type": "quote",
"name": "Quote",
"settings": [
{ "type": "textarea", "id": "text", "label": "Quote" },
{ "type": "text", "id": "author", "label": "Author" }
]
}
],
"max_blocks": 8,
"presets": [
{
"name": "Customer quotes",
"blocks": [
{ "type": "quote", "settings": { "text": "Lovely quality, fast delivery.", "author": "Sara" } },
{ "type": "quote", "settings": { "text": "My new favourite store.", "author": "Omar" } }
]
}
]
}
{% endschema %}

Builder blocks (heading, text, button, image, product card, buy buttons, variant picker, group, and others) go into a section that accepts "@theme" or names their type. Place them like block files, with {% content_for 'blocks' %} or {% render_block block %}, and the store draws them exactly as in its own sections. block.builder is true for them.

Product blocks show the product picked in the section’s product setting, or the page’s product when there isn’t one.

A snippet is a reusable piece of template with no schema. Pass it the variables it needs; it can’t see the caller’s other variables.

{% render 'product-card', product: product %}
<a class="card" href="{{ product.url }}">
{% if product.featured_image %}{{ product.featured_image | image_tag: class: 'card__image' }}{% endif %}
<span class="card__title">{{ product.title }}</span>
<span class="card__price">
{{ product.price | money }}
{% if product.on_sale %}<s>{{ product.compare_at_price | money }}</s>{% endif %}
</span>
{% unless product.available %}<span class="card__badge">{{ 'sold_out' | t }}</span>{% endunless %}
</a>

{% paginate %} shows a list one page at a time. The URL’s ?page= picks the page, and {{ paginate | default_pagination }} draws the page links. You can also build your own pager from paginate.parts, paginate.previous.url, and paginate.next.url.

{% paginate collection.products by 12 %}
{% for product in collection.products %}
{% render 'product-card', product: product %}
{% endfor %}
{{ paginate | default_pagination }}
{% endpaginate %}

It works for collection.products on collection pages, section.settings.<collection>.products, and search.results on the search page, with up to 48 items a page. Without {% paginate %}, a collection gives its first 24 products.

A theme can’t write its own <form> element; it is removed. Use the {% form %} tag instead, and the store sends the form for you:

Form Sends to Fields
{% form 'contact' %} The store’s inbox and contacts, like the built-in Contact form email, name, phone, message (or contact[email]…), plus any other named fields
{% form 'newsletter' %} The store’s contacts, like the built-in Email signup email
{% form 'product', product %} The cart variant_id (defaults to the first available variant) and quantity

Mark what to show afterwards with data-sf-form-success and data-sf-form-error:

{% form 'newsletter' %}
<input type="email" name="email" required>
<button>{{ 'Join' | t: ar: 'اشترك' }}</button>
<p data-sf-form-success>{{ 'Thanks!' | t: ar: 'شكراً!' }}</p>
<p data-sf-form-error></p>
{% endform %}

While it’s being sent, the form carries data-state = sending, success, or error for your CSS. Forms need the store’s own script, so they don’t post without JavaScript in the shopper’s browser.

Theme code can’t run JavaScript. Instead, add these data-sf-* attributes and the store makes them work, in the builder preview too:

Behaviour Attributes What it does
Tabs data-sf-tabs, data-sf-tab, data-sf-panel A wrapper with buttons data-sf-tab="k" and panels data-sf-panel="k". The first panel is open.
Accordion data-sf-accordion, data-sf-trigger, data-sf-content, data-sf-open A button data-sf-trigger="k" opens and closes data-sf-content="k". data-sf-accordion="single" keeps one open; data-sf-open starts one open.
Slider data-sf-carousel, data-sf-track, data-sf-slide, data-sf-prev, data-sf-next, data-sf-dots, data-sf-autoplay A horizontally scrolling track of slides with arrows, dots, and autoplay in milliseconds (off for reduced motion).
Countdown data-sf-countdown, data-sf-days, data-sf-hours, data-sf-minutes, data-sf-seconds Counts down to an ISO date, such as a datetime setting. Optional children receive the numbers.
Pop-up data-sf-modal, data-sf-modal-open, data-sf-modal-close, data-sf-modal-delay A modal opened by data-sf-modal-open="k" buttons and closed by data-sf-modal-close, Escape, or a click outside. data-sf-modal-delay="3000" opens it once per visit after a delay.
Show more data-sf-show-more, data-sf-show-more-button Shows the first N children of a list (data-sf-show-more="N") and the rest when the button is pressed.
Copy data-sf-copy A button that copies text, such as a discount code.
Reveal data-sf-reveal Animates in on scroll: fade, fade-up, fade-down, zoom, slide-start, slide-end.
Lightbox data-sf-lightbox Opens a picture full screen. data-sf-lightbox="g" groups pictures with arrows.
Form status data-sf-form-success, data-sf-form-error Inside {% form %}: shown after the form was sent, or when it failed.
Cart data-sf-cart Shows the shopper’s live cart: data-sf-cart="count" (items) or "total" (formatted total).

For example, a pop-up:

<button data-sf-modal-open="news">Join</button>
<div data-sf-modal="news" class="modal">
<div class="modal__box">… <button data-sf-modal-close>Close</button></div>
</div>

Pixels and chat widgets come from the store’s own integrations, not from theme code.

The server checks every file each time it is saved, pushed, or validated, and reports problems as file:line:column message:

sections/promo.liquid:3:1 <script> isn't allowed: theme code can't run JavaScript. Use the data-sf-* behaviours instead.
sections/staff-picks.liquid:7:9 Snippet "product-card" doesn't exist: add snippets/product-card.liquid.
snippets/card.liquid:8:3 warning: data-sf-zoom isn't one of the data-sf-* behaviours; it is removed when drawn.

Errors stop repzo store push and block publishing everywhere: in the builder, the CLI, the API, and a scheduled publish. Errors include broken Liquid, invalid schema JSON, unknown filters, tags, or setting types, missing snippets or block files, <script>, and size limits. Warnings, such as a removed tag or an unknown data-sf-* attribute, don’t stop anything.

Files saved one at a time (in the builder’s Code view or with repzo store code put) are kept even when they have errors, because they are only a draft. A section with errors draws nothing on the live store, and the builder shows its problem in its place.

Common fixes:

Problem Fix
Unknown filter Use a filter from the reference (| money, not | format_money).
{% schema %} isn't valid JSON No trailing commas or comments. Keys and strings use double quotes.
Unknown setting type Use a type from the setting types table (image_picker, not image_upload).
Missing snippet {% render 'name' %} needs snippets/name.liquid.
<script> or onclick Remove it and use a ready-made behaviour.
A setting id used in the template but not in the schema Add it to settings, or fix the spelling.
The section isn’t in Add section Give it presets.
The page shows nothing for a product or collection product and collection are only set on their own pages. Elsewhere, use a product or collection setting.
  • No JavaScript. <script>, on*= attributes (onclick…), javascript: links, and {% javascript %} are errors. <iframe>, <object>, <embed>, <form>, and <style> are removed when drawn. CSS goes in {% stylesheet %}.
  • Output is sanitized like the builder’s AI blocks, and CSS is scoped to its section or block (no @import, no url(javascript:…)).
  • Templates only read data. {% render %} only finds this theme’s snippets. {% include %}, {% layout %}, {% section %}, and {% sections %} aren’t available.
  • Values aren’t escaped automatically. Use | escape for text you print inside attributes.
  • cart is always empty when the page is drawn, because pages are cached for every shopper. Show the live cart with data-sf-cart.
  • Up to 60 code files per theme, 48 KB per file, and 512 KB in all. {% stylesheet %} is cut at 16 KB.
  • Each section gets 250 ms of render time and 256 KB of HTML, and loops are memory-capped.