Shopify Liquid Themes

Shopify Liquid Themes

Theme Architecture

.├── sections/    # Full-width page modules with {% schema %} — hero, product grid, testimonials├── blocks/      # Nestable components with {% schema %} — slides, feature items, text blocks├── snippets/    # Reusable fragments via {% render %} — buttons, icons, image helpers├── layout/      # Page wrappers (must include {{ content_for_header }} and {{ content_for_layout }})├── templates/   # JSON files defining which sections appear on each page type├── config/      # Global theme settings (settings_schema.json, settings_data.json)├── locales/     # Translation files (en.default.json, fr.json, etc.)└── assets/      # Static CSS, JS, images (prefer {% stylesheet %}/{% javascript %} instead)

When to use what

Liquid Syntax

Delimiters

• {{ ... }} — Output (prints a value)
• {{- ... -}} — Output with whitespace trimming
• {% ... %} — Logic tag (if, for, assign) — prints nothing
• {%- ... -%} — Logic tag with whitespace trimming

Operators

Comparison: ==, !=, >, <, >=, <= Logical: and, or, contains

Critical Gotchas

1. No parentheses in conditions — use nested {% if %} instead
2. No ternary — always use {% if cond %}value{% else %}other{% endif %}
3. for loops max 50 iterations — use {% paginate %} for larger arrays
4. contains only works with strings — can't check objects in arrays
5. {% stylesheet %}/{% javascript %} don't render Liquid — no Liquid inside them
6. Snippets can't access outer-scope variables — pass them as render params
7. include is deprecated — always use {% render 'snippet_name' %}
8. {% liquid %} tag — multi-line logic without delimiters; use echo for output

Variables

{% assign my_var = 'value' %}{% capture my_var %}computed {{ value }}{% endcapture %}{% increment counter %}{% decrement counter %}

Filter Quick Reference

Filters are chained with |. Output type of one filter feeds input of next.

Array: compact, concat, find, find_index, first, has, join, last, map, reject, reverse, size, sort, sort_natural, sum, uniq, where String: append, capitalize, downcase, escape, handleize, lstrip, newline_to_br, prepend, remove, replace, rstrip, slice, split, strip, strip_html, truncate, truncatewords, upcase, url_decode, url_encode Math: abs, at_least, at_most, ceil, divided_by, floor, minus, modulo, plus, round, times Money: money, money_with_currency, money_without_currency, money_without_trailing_zeros Color: color_brightness, color_darken, color_lighten, color_mix, color_modify, color_saturate, color_desaturate, color_to_hex, color_to_hsl, color_to_rgb Media: image_url, image_tag, video_tag, external_video_tag, media_tag, model_viewer_tag URL: asset_url, asset_img_url, file_url, shopify_asset_url HTML: link_to, script_tag, stylesheet_tag, time_tag, placeholder_svg_tag Localization: t (translate), format_address, currency_selector Other: date, default, json, structured_data, font_face, font_url, payment_button

Full details: language filters [blocked], HTML/media filters [blocked], commerce filters [blocked]

Tags Quick Reference

Full details with syntax and parameters: references/tags.md [blocked]

Objects Quick Reference

Global objects (available everywhere)

cart, collections, customer, localization, pages, request, routes, settings, shop, template, theme, linklists, images, blogs, articles, all_products, metaobjects, canonical_url, content_for_header, content_for_layout, page_title, page_description, handle, current_page

Page-specific objects

Full reference: commerce objects [blocked], content objects [blocked], tier 2 [blocked], tier 3 [blocked]

Schema Tag

Sections and blocks require {% schema %} with a valid JSON object. Sections use section.settings.*, blocks use block.settings.*.

Section schema structure

{  "name": "t:sections.hero.name",  "tag": "section",  "class": "hero-section",  "limit": 1,  "settings": [],  "max_blocks": 16,  "blocks": [{ "type": "@theme" }],  "presets": [{ "name": "t:sections.hero.name" }],  "enabled_on": { "templates": ["index"] },  "disabled_on": { "templates": ["password"] }}

Block schema structure

{  "name": "t:blocks.slide.name",  "tag": "div",  "class": "slide",  "settings": [],  "blocks": [{ "type": "@theme" }],  "presets": [{ "name": "t:blocks.slide.name" }]}

Setting type decision table

visible_if pattern

{  "visible_if": "{{ block.settings.layout == 'vertical' }}",  "type": "select",  "id": "alignment",  "label": "t:labels.alignment",  "options": [...]}

Conditionally shows/hides a setting in the editor based on other setting values.

Block entry types

• { "type": "@theme" } — Accept any theme block
• { "type": "@app" } — Accept app blocks
• { "type": "slide" } — Accept only the slide block type

Full schema details and all 33 setting types: references/schema-and-settings.md [blocked]

CSS & JavaScript

Per-component styles and scripts

Use {% stylesheet %} and {% javascript %} in sections, blocks, and snippets:

{% stylesheet %}  .my-component { display: flex; }{% endstylesheet %}
{% javascript %}  console.log('loaded');{% endjavascript %}

• One tag each per file — multiple {% stylesheet %} tags will error
• No Liquid inside — these tags don't process Liquid; use CSS variables or classes instead
• Only supported in sections/, blocks/, and snippets/

{% style %} tag (Liquid-aware CSS)

For dynamic CSS that needs Liquid (e.g., color settings that live-update in editor):

{% style %}  .section-{{ section.id }} {    background: {{ section.settings.bg_color }};  }{% endstyle %}

CSS patterns for settings

Single CSS property — use CSS variables:

<div style="--gap: {{ block.settings.gap }}px">

Multiple CSS properties — use CSS classes as select values:

<div class="{{ block.settings.layout }}">

LiquidDoc ({% doc %})

Required for: snippets (always), blocks (when statically rendered via {% content_for 'block' %})

{% doc %}  Brief description of what this file renders.
  @param {type} name - Description of required parameter  @param {type} [name] - Description of optional parameter (brackets = optional)
  @example  {% render 'snippet-name', name: value %}{% enddoc %}

Param types: string, number, boolean, image, object, array

Translations

Every user-facing string must use the t filter

<!-- Correct --><h2>{{ 'sections.hero.heading' | t }}</h2><button>{{ 'products.add_to_cart' | t }}</button>
<!-- Wrong — never hardcode strings --><h2>Welcome to our store</h2>

Variable interpolation

{{ 'products.price_range' | t: min: product.price_min | money, max: product.price_max | money }}

Locale file:

{  "products": {    "price_range": "From {{ min }} to {{ max }}"  }}

Locale file structure

locales/├── en.default.json          # English translations (required)├── en.default.schema.json   # Editor setting translations (required)├── fr.json                  # French translations└── fr.schema.json           # French editor translations

Key naming conventions

• Use snake_case and hierarchical keys (max 3 levels)
• Use sentence case for all text (capitalize first word only)
• Schema labels use t: prefix: "label": "t:labels.heading"
• Group by component: sections.hero.heading, blocks.slide.title

References

• Filters: language [blocked] (77), HTML/media [blocked] (45), commerce [blocked] (30)
• Tag reference (30 tags) [blocked]
• Objects: commerce [blocked] (5), content [blocked] (10), tier 2 [blocked] (69), tier 3 [blocked] (53)
• Schema & settings reference (33 types) [blocked]
• Complete examples (snippet, block, section) [blocked]