Shopify Liquid Templating
Before writing code
Fetch live docs:
- Fetch
https://shopify.dev/docs/api/liquid for Liquid reference
- Web-search
site:shopify.dev liquid objects for available objects
- 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.
1---2name: shopify-liquid3description: 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.4allowed-tools: Read, Write, Edit, Bash, Grep, Glob, WebSearch, WebFetch5metadata:6 source: https://skillmd.com/skills/orcaqubits/shopify-liquid7---89# Shopify Liquid Templating1011## Before writing code1213**Fetch live docs**:141. Fetch `https://shopify.dev/docs/api/liquid` for Liquid reference152. Web-search `site:shopify.dev liquid objects` for available objects163. Web-search `site:shopify.dev liquid filters` for available filters1718## What Is Liquid1920Liquid is Shopify's template language:21- Ruby-based, open-source (created by Shopify)22- Renders on Shopify's servers — no client-side execution23- Three building blocks: **objects**, **tags**, **filters**24- Shopify extends standard Liquid with commerce-specific objects and filters2526## Objects2728Access data with double curly braces:29- `{{ product.title }}` — product name30- `{{ product.price | money }}` — formatted price31- `{{ cart.item_count }}` — number of items in cart3233### Key Global Objects3435| Object | Description |36|--------|-------------|37| `product` | Current product (on product pages) |38| `collection` | Current collection |39| `cart` | Shopping cart |40| `customer` | Logged-in customer (nil if guest) |41| `shop` | Store settings |42| `request` | Current request (locale, page type) |43| `content_for_header` | Required scripts/meta (must be in layout) |44| `content_for_layout` | Template content (must be in layout) |45| `all_products` | Access any product by handle |46| `collections` | All collections |47| `linklists` | Navigation menus |48| `pages` | CMS pages |49| `settings` | Theme settings |5051## Tags5253Control flow and logic:5455### Control Flow56```liquid57{% if product.available %}58 <span>In stock</span>59{% elsif product.variants.size > 0 %}60 <span>Limited</span>61{% else %}62 <span>Sold out</span>63{% endif %}6465{% unless customer %}66 <a href="/account/login">Log in</a>67{% endunless %}6869{% case product.type %}70 {% when 'Shirt' %}71 <p>Clothing</p>72 {% when 'Mug' %}73 <p>Accessories</p>74{% endcase %}75```7677### Iteration78```liquid79{% for product in collection.products %}80 <h2>{{ product.title }}</h2>81{% endfor %}8283{% for item in cart.items limit:5 offset:2 %}84 {{ item.title }}85{% endfor %}8687{% paginate collection.products by 12 %}88 {% for product in collection.products %}89 {{ product.title }}90 {% endfor %}91 {{ paginate | default_pagination }}92{% endpaginate %}93```9495### Variable96```liquid97{% assign greeting = 'Hello' %}98{% capture full_greeting %}{{ greeting }}, {{ customer.first_name }}!{% endcapture %}99```100101## Filters102103Transform output:104- **String**: `upcase`, `downcase`, `strip`, `truncate`, `replace`, `split`, `url_encode`105- **Number**: `plus`, `minus`, `times`, `divided_by`, `round`, `ceil`, `floor`106- **Money**: `money`, `money_with_currency`, `money_without_trailing_zeros`107- **Date**: `date: '%B %d, %Y'`108- **Array**: `first`, `last`, `size`, `sort`, `map`, `where`, `join`, `uniq`109- **HTML**: `img_tag`, `script_tag`, `stylesheet_tag`110- **URL**: `asset_url`, `img_url`, `file_url`, `shopify_asset_url`111- **Media**: `image_url`, `image_tag` (modern replacements for `img_url`/`img_tag`)112113## Section Schema114115Sections define their own settings in a `{% schema %}` tag:116117```liquid118{% schema %}119{120 "name": "Featured Product",121 "settings": [122 {123 "type": "product",124 "id": "product",125 "label": "Product"126 },127 {128 "type": "color",129 "id": "background_color",130 "label": "Background color",131 "default": "#ffffff"132 }133 ],134 "blocks": [135 {136 "type": "text",137 "name": "Text block",138 "settings": [139 {140 "type": "richtext",141 "id": "content",142 "label": "Content"143 }144 ]145 }146 ],147 "presets": [148 {149 "name": "Featured Product"150 }151 ]152}153{% endschema %}154```155156## JSON Templates (Online Store 2.0)157158Templates are JSON files that reference sections:159160```json161{162 "sections": {163 "main": {164 "type": "main-product",165 "settings": {}166 },167 "recommendations": {168 "type": "product-recommendations",169 "settings": {170 "heading": "You may also like"171 }172 }173 },174 "order": ["main", "recommendations"]175}176```177178## Deprecated — Do NOT Reference179180- **Timber** — deprecated starter theme; use Dawn instead181- Section-only themes without JSON templates (pre-Online Store 2.0)182183## Best Practices184185- Use `image_url` and `image_tag` instead of deprecated `img_url` / `img_tag`186- Use JSON templates for all page types (Online Store 2.0)187- Keep logic minimal — Liquid is a template language, not a programming language188- Use `{% comment %}` for documentation, not HTML comments (which are sent to the browser)189- Use snippets (`{% render 'snippet-name' %}`) for reusable code — `{% include %}` is deprecated190- Use `{% render %}` over `{% include %}` — render creates an isolated scope191- Apply `| escape` filter to user-generated content to prevent XSS192- Use section settings for merchant-configurable values instead of hardcoding193194Fetch the Shopify Liquid reference for exact object properties, available filters, and section schema options before implementing.