shopify-liquid

name	shopify-liquid
description	Write Shopify Liquid templates — objects, tags, filters, global objects, section schema, Online Store 2.0 JSON templates, and Liquid best practices. Use when customizing Shopify theme templates.
allowed-tools	Read, Write, Edit, Bash, Grep, Glob, WebSearch, WebFetch

Shopify Liquid Templating

Before writing code

Fetch live docs:

1. Fetch https://shopify.dev/docs/api/liquid for Liquid reference
2. Web-search site:shopify.dev liquid objects for available objects
3. Web-search site:shopify.dev liquid filters for available filters

What Is Liquid

Liquid is Shopify's template language:

• Ruby-based, open-source (created by Shopify)
• Renders on Shopify's servers — no client-side execution
• Three building blocks: objects, tags, filters
• Shopify extends standard Liquid with commerce-specific objects and filters

Objects

Access data with double curly braces:

• {{ product.title }} — product name
• {{ product.price | money }} — formatted price
• {{ cart.item_count }} — number of items in cart

Key Global Objects

Object	Description
product	Current product (on product pages)
collection	Current collection
cart	Shopping cart
customer	Logged-in customer (nil if guest)
shop	Store settings
request	Current request (locale, page type)
content_for_header	Required scripts/meta (must be in layout)
content_for_layout	Template content (must be in layout)
all_products	Access any product by handle
collections	All collections
linklists	Navigation menus
pages	CMS pages
settings	Theme settings

Tags

Control flow and logic:

Control Flow

{% if product.available %}
  <span>In stock</span>
{% elsif product.variants.size > 0 %}
  <span>Limited</span>
{% else %}
  <span>Sold out</span>
{% endif %}

{% unless customer %}
  <a href="/account/login">Log in</a>
{% endunless %}

{% case product.type %}
  {% when 'Shirt' %}
    <p>Clothing</p>
  {% when 'Mug' %}
    <p>Accessories</p>
{% endcase %}

Iteration

{% for product in collection.products %}
  <h2>{{ product.title }}</h2>
{% endfor %}

{% for item in cart.items limit:5 offset:2 %}
  {{ item.title }}
{% endfor %}

{% paginate collection.products by 12 %}
  {% for product in collection.products %}
    {{ product.title }}
  {% endfor %}
  {{ paginate | default_pagination }}
{% endpaginate %}

Variable

{% assign greeting = 'Hello' %}
{% capture full_greeting %}{{ greeting }}, {{ customer.first_name }}!{% endcapture %}

Filters

Transform output:

• String: upcase, downcase, strip, truncate, replace, split, url_encode
• Number: plus, minus, times, divided_by, round, ceil, floor
• Money: money, money_with_currency, money_without_trailing_zeros
• Date: date: '%B %d, %Y'
• Array: first, last, size, sort, map, where, join, uniq
• HTML: img_tag, script_tag, stylesheet_tag
• URL: asset_url, img_url, file_url, shopify_asset_url
• Media: image_url, image_tag (modern replacements for img_url/img_tag)

Section Schema

Sections define their own settings in a {% schema %} tag:

{% schema %}
{
  "name": "Featured Product",
  "settings": [
    {
      "type": "product",
      "id": "product",
      "label": "Product"
    },
    {
      "type": "color",
      "id": "background_color",
      "label": "Background color",
      "default": "#ffffff"
    }
  ],
  "blocks": [
    {
      "type": "text",
      "name": "Text block",
      "settings": [
        {
          "type": "richtext",
          "id": "content",
          "label": "Content"
        }
      ]
    }
  ],
  "presets": [
    {
      "name": "Featured Product"
    }
  ]
}
{% endschema %}

JSON Templates (Online Store 2.0)

Templates are JSON files that reference sections:

{
  "sections": {
    "main": {
      "type": "main-product",
      "settings": {}
    },
    "recommendations": {
      "type": "product-recommendations",
      "settings": {
        "heading": "You may also like"
      }
    }
  },
  "order": ["main", "recommendations"]
}

Deprecated — Do NOT Reference

• Timber — deprecated starter theme; use Dawn instead
• Section-only themes without JSON templates (pre-Online Store 2.0)

Best Practices

• Use image_url and image_tag instead of deprecated img_url / img_tag
• Use JSON templates for all page types (Online Store 2.0)
• Keep logic minimal — Liquid is a template language, not a programming language
• Use {% comment %} for documentation, not HTML comments (which are sent to the browser)
• Use snippets ({% render 'snippet-name' %}) for reusable code — {% include %} is deprecated
• Use {% render %} over {% include %} — render creates an isolated scope
• Apply | escape filter to user-generated content to prevent XSS
• Use section settings for merchant-configurable values instead of hardcoding

Fetch the Shopify Liquid reference for exact object properties, available filters, and section schema options before implementing.