Liquid tags
Liquid tags are used to define logic that tells templates what to do.
## Tags
Liquid tags are used to define logic that tells templates what to do.
### Tags with parameters
Certain tags accept parameters. Some tags have required parameters, and others are optional. For example, the `for` tag can accept parameters like `limit` to exit a loop at a specific index.
### Usage
Tags are wrapped with curly brace percentage delimiters `{% %}`. The text within the delimiters doesn't produce visible output when rendered.
In the example below, the `if` tag defines the condition to be met. If `product.available` returns `true`, then the price is displayed. Otherwise, the "sold-out" message is shown.
> **Tip:** You can nest multiple tags inside one set of delimiters using the [`liquid` tag](/docs/api/liquid/tags/liquid).
## Conditional tags
Conditional tags define conditions that determine whether blocks of Liquid code get executed.
### case
Deprecated: false
{% case variable %}
{% when first_value %}
first_expression
{% when second_value %}
second_expression
{% else %}
third_expression
{% endcase %}
Renders a specific expression depending on the value of a specific variable.
#### Examples
code:
{% case product.type %}
{% when 'Health' %}
This is a health potion.
{% when 'Love' %}
This is a love potion.
{% else %}
This is a potion.
{% endcase %}
data:
{"product":{"type":null}}
output:
This is a health potion.
code:
{% case product.type %}
{% when 'Love' or 'Luck' %}
This is a love or luck potion.
{% when 'Strength','Health' %}
This is a strength or health potion.
{% else %}
This is a potion.
{% endcase %}
data:
{"product":{"type":null}}
output:
This is a strength or health potion.
### else
Deprecated: false
{% else %}
expression
Allows you to specify a default expression to execute when no other condition is met.
#### Examples
code:
{% if product.available %}
This product is available!
{% else %}
This product is sold out!
{% endif %}
data:
{"product":{"available":true}}
output:
This product is available!
### if
Deprecated: false
{% if condition %}
expression
{% endif %}
Renders an expression if a specific condition is `true`.
#### Examples
code:
{% if product.compare_at_price > product.price %}
This product is on sale!
{% endif %}
data:
{"product":{"compare_at_price":"10.00","price":"0.00"}}
output:
This product is on sale!
code:
{% if product.type == 'Love' %}
This is a love potion!
{% elsif product.type == 'Health' %}
This is a health potion!
{% endif %}
data:
{"product":{"type":null}}
output:
This is a health potion!
### unless
Deprecated: false
{% unless condition %}
expression
{% endunless %}
Renders an expression unless a specific condition is `true`.
#### Examples
code:
{% unless product.has_only_default_variant %}
// Variant selection functionality
{% endunless %}
data:
{"product":{"has_only_default_variant":false}}
output:
// Variant selection functionality
## HTML tags
HTML tags render HTML elements using Shopify-specific attributes.
### form
Deprecated: false
{% form 'form_type' %}
content
{% endform %}
Generates an HTML `
code:
{% form 'cart', cart %}
{% endform %}
data:
{}
output:
code:
{% form 'contact' %}
{% endform %}
data:
{}
output:
code:
{% form 'create_customer' %}
{% endform %}
data:
{}
output:
code:
{% form 'currency' %}
{{ form | currency_selector }}
{% endform %}
data:
{}
output:
code:
{% form 'customer' %}
{% endform %}
data:
{}
output:
code:
{% form 'customer_address', customer.new_address %}
{% endform %}
data:
{}
output:
code:
{% form 'customer_login' %}
{% endform %}
data:
{}
output:
code:
{% form 'guest_login' %}
{% endform %}
data:
{}
output:
code:
{% form 'localization' %}
{% endform %}
data:
{}
output:
code:
{% form 'new_comment', article %}
{% endform %}
data:
{}
output:
code:
{% form 'product', product %}
{% endform %}
data:
{"product":{"id":6786188247105}}
output:
code:
{% form 'recover_customer_password' %}
{% endform %}
data:
{}
output:
code:
{% form 'reset_customer_password' %}
{% endform %}
data:
{}
output:
code:
{% form 'storefront_password' %}
{% endform %}
data:
{}
output:
code:
{% form 'customer_login', return_to: routes.root_url %}
{% endform %}
data:
{"routes":{"root_url":"/"}}
output:
code:
{% form "product", product, id: 'custom-id', class: 'custom-class', data-example: '100' %}
{% endform %}
data:
{"product":{"id":6786188247105}}
output:
### style
Deprecated: false
{% style %}
CSS_rules
{% endstyle %}
Generates an HTML `
## Iteration tags
Iteration tags repeatedly run blocks of code.
### break
Deprecated: false
{% break %}
Stops a [`for` loop](/docs/api/liquid/tags/for) from iterating.
#### Examples
code:
{% for i in (1..5) -%}
{%- if i == 4 -%}
{% break %}
{%- else -%}
{{ i }}
{%- endif -%}
{%- endfor %}
data:
{}
output:
1
2
3
### continue
Deprecated: false
{% continue %}
Causes a [`for` loop](/docs/api/liquid/tags/for) to skip to the next iteration.
#### Examples
code:
{% for i in (1..5) -%}
{%- if i == 4 -%}
{% continue %}
{%- else -%}
{{ i }}
{%- endif -%}
{%- endfor %}
data:
{}
output:
1
2
3
5
### cycle
Deprecated: false
{% cycle string, string, ... %}
Loops through a group of strings and outputs them one at a time for each iteration of a [`for` loop](/docs/api/liquid/tags/for).
#### Examples
code:
{% for i in (1..4) -%}
{% cycle 'one', 'two', 'three' %}
{%- endfor %}
data:
{}
output:
one
two
three
one
code:
{% for i in (1..4) -%}
{% cycle 'one', 'two', 'three' %}
{%- endfor %}
{% for i in (1..4) -%}
{% cycle 'one', 'two', 'three' %}
{%- endfor %}
{% for i in (1..4) -%}
{% cycle 'group_1': 'one', 'two', 'three' %}
{%- endfor %}
{% for i in (1..4) -%}
{% cycle 'group_2': 'one', 'two', 'three' %}
{%- endfor %}
data:
{}
output:
one
two
three
one
two
three
one
two
one
two
three
one
one
two
three
one
### else
Deprecated: false
{% for variable in array %}
first_expression
{% else %}
second_expression
{% endfor %}
Allows you to specify a default expression to execute when a [`for` loop](/docs/api/liquid/tags/for) has zero length.
#### Examples
code:
{% for product in collection.products %}
{{ product.title }}
{% else %}
There are no products in this collection.
{% endfor %}
data:
{"collection":{"products":[]}}
output:
There are no products in this collection.
### for
Deprecated: false
{% for variable in array %}
expression
{% endfor %}
Renders an expression for every item in an array.
#### Examples
code:
{% for product in collection.products -%}
{{ product.title }}
{%- endfor %}
data:
{"collection":{"products":[{"title":"Draught of Immortality"},{"title":"Glacier ice"},{"title":"Health potion"},{"title":"Invisibility potion"}]}}
output:
Draught of Immortality
Glacier ice
Health potion
Invisibility potion
code:
{% for product in collection.products limit: 2 -%}
{{ product.title }}
{%- endfor %}
data:
{"collection":{"products":[{"title":"Draught of Immortality"},{"title":"Glacier ice"},{"title":"Health potion"},{"title":"Invisibility potion"}]}}
output:
Draught of Immortality
Glacier ice
code:
{% for product in collection.products offset: 2 -%}
{{ product.title }}
{%- endfor %}
data:
{"collection":{"products":[{"title":"Draught of Immortality"},{"title":"Glacier ice"},{"title":"Health potion"},{"title":"Invisibility potion"}]}}
output:
Health potion
Invisibility potion
code:
{% for i in (1..3) -%}
{{ i }}
{%- endfor %}
{%- assign lower_limit = 2 -%}
{%- assign upper_limit = 4 -%}
{% for i in (lower_limit..upper_limit) -%}
{{ i }}
{%- endfor %}
data:
{}
output:
1
2
3
2
3
4
code:
{% for product in collection.products reversed -%}
{{ product.title }}
{%- endfor %}
data:
{"collection":{"products":[{"title":"Draught of Immortality"},{"title":"Glacier ice"},{"title":"Health potion"},{"title":"Invisibility potion"}]}}
output:
Invisibility potion
Health potion
Glacier ice
Draught of Immortality
### paginate
Deprecated: false
{% paginate array by page_size %}
{% for item in array %}
forloop_content
{% endfor %}
{% endpaginate %}
The `paginate` tag allows the user to paginate to the 25,000'nth item in the array an no further. To reach items further in
the array the array should be filtered further before paginating. See
[Pagination Limits](/themes/best-practices/performance/platform#pagination-limits) for more information.
Splits an array's items across multiple pages.
#### Examples
code:
{% paginate collection.products by 5 %}
{% for product in collection.products -%}
{{ product.title }}
{%- endfor %}
{{- paginate | default_pagination }}
{% endpaginate %}
data:
{"collection":{"products":[{"title":"Blue Mountain Flower"},{"title":"Charcoal"},{"title":"Crocodile tears"},{"title":"Dandelion milk"},{"title":"Draught of Immortality"}],"products_count":19}}
output:
Blue Mountain Flower
Charcoal
Crocodile tears
Dandelion milk
Draught of Immortality
1 2 3 4 Next »
code:
data:
{}
output:
code:
{% paginate collection.products by 4 %}
{% for product in collection.products limit: 4 -%}
{{ product.title }}
{%- endfor %}
{% endpaginate -%}
{% for product in collection.products limit: 4 -%}
{{ product.title }}
{%- endfor -%}
data:
{"collection":{"products":[{"title":"Blue Mountain Flower"},{"title":"Charcoal"},{"title":"Crocodile tears"},{"title":"Dandelion milk"}],"products_count":19}}
output:
Blue Mountain Flower
Charcoal
Crocodile tears
Dandelion milk
Blue Mountain Flower
Charcoal
Crocodile tears
Dandelion milk
code:
{% paginate collection.products by 3, window_size: 1 %}
{% for product in collection.products -%}
{{ product.title }}
{%- endfor %}
{{- paginate | default_pagination }}
{% endpaginate %}
data:
{"collection":{"products":[{"title":"Blue Mountain Flower"},{"title":"Charcoal"},{"title":"Crocodile tears"}],"products_count":19}}
output:
Blue Mountain Flower
Charcoal
Crocodile tears
1 … 7 Next »
### tablerow
Deprecated: false
{% tablerow variable in array %}
expression
{% endtablerow %}
Generates HTML table rows for every item in an array.
#### Examples
code:
{% tablerow product in collection.products %}
{{ product.title }}
{% endtablerow %}
data:
{"collection":{"products":[{"title":"Draught of Immortality"},{"title":"Glacier ice"},{"title":"Health potion"},{"title":"Invisibility potion"}]}}
output:
Draught of Immortality
|
Glacier ice
|
Health potion
|
Invisibility potion
|
code:
{% tablerow product in collection.products cols: 2 %}
{{ product.title }}
{% endtablerow %}
data:
{"collection":{"products":[{"title":"Draught of Immortality"},{"title":"Glacier ice"},{"title":"Health potion"},{"title":"Invisibility potion"}]}}
output:
Draught of Immortality
|
Glacier ice
|
Health potion
|
Invisibility potion
|
code:
{% tablerow product in collection.products limit: 2 %}
{{ product.title }}
{% endtablerow %}
data:
{"collection":{"products":[{"title":"Draught of Immortality"},{"title":"Glacier ice"},{"title":"Health potion"},{"title":"Invisibility potion"}]}}
output:
Draught of Immortality
|
Glacier ice
|
code:
{% tablerow product in collection.products offset: 2 %}
{{ product.title }}
{% endtablerow %}
data:
{"collection":{"products":[{"title":"Draught of Immortality"},{"title":"Glacier ice"},{"title":"Health potion"},{"title":"Invisibility potion"}]}}
output:
Health potion
|
Invisibility potion
|
code:
{% tablerow i in (1..3) %}
{{ i }}
{% endtablerow %}
{%- assign lower_limit = 2 -%}
{%- assign upper_limit = 4 -%}
{% tablerow i in (lower_limit..upper_limit) %}
{{ i }}
{% endtablerow %}
data:
{}
output:
## Syntax tags
Syntax tags control how Liquid code is processed and rendered.
### comment
Deprecated: false
{% comment %}
content
{% endcomment %}
Prevents an expression from being rendered or output.
#### Examples
code:
{% # this is a comment %}
{% # for i in (1..3) -%}
{{ i }}
{% # endfor %}
{%
###############################
# This is a comment
# across multiple lines
###############################
%}
data:
{}
output:
code:
{% liquid
# this is a comment
assign topic = 'Learning about comments!'
echo topic
%}
data:
{}
output:
Learning about comments!
### doc
Deprecated: false
{% doc %}
Renders a message.
@param {string} foo - A string value.
@param {string} [bar] - An optional string value.
@example
{% render 'message', foo: 'Hello', bar: 'World' %}
{% enddoc %}
{{ foo }}, {{ bar }}!
Documents template elements with annotations.
#### Examples
### echo
Deprecated: false
{% liquid
echo expression
%}
Outputs an expression.
#### Examples
code:
{% echo product.title %}
{% liquid
echo product.price | money
%}
data:
{"product":{"price":"10.00","title":"Health potion"}}
output:
Health potion
$10.00
### liquid
Deprecated: false
{% liquid
expression
%}
Allows you to have a block of Liquid without delimeters on each tag.
#### Examples
code:
{% liquid
# Show a message that's customized to the product type
assign product_type = product.type | downcase
assign message = ''
case product_type
when 'health'
assign message = 'This is a health potion!'
when 'love'
assign message = 'This is a love potion!'
else
assign message = 'This is a potion!'
endcase
echo message
%}
data:
{"product":{"type":null}}
output:
This is a health potion!
### raw
Deprecated: false
{% raw %}
expression
{% endraw %}
Outputs any Liquid code as text instead of rendering it.
#### Examples
code:
{% raw %}
{{ 2 | plus: 2 }} equals 4.
{% endraw %}
data:
{}
output:
{{ 2 | plus: 2 }} equals 4.
## Theme tags
Theme tags assign or render content that’s part of your [theme](/themes/architecture).
### content_for
Deprecated: false
{% content_for 'blocks' %}
{% content_for 'block', type: "slide", id: "slide-1" %}
Creates a designated area in your theme where blocks can be rendered.
#### Examples
code:
data:
{}
output:
code:
data:
{}
output:
### include
Deprecated: true
{% include 'filename' %}
Renders a [snippet](/themes/architecture/snippets).
#### Examples
### javascript
Deprecated: false
{% javascript %}
javascript_code
{% endjavascript %}
JavaScript code included in [section](/storefronts/themes/architecture/sections), [block](/storefronts/themes/architecture/blocks) and [snippet](/storefronts/themes/architecture/snippets) files.
#### Examples
### layout
Deprecated: false
{% layout name %}
Specify which [layout](/themes/architecture/layouts) to use.
#### Examples
code:
data:
output:
### render
Deprecated: false
{% render 'filename' %}
Renders a [snippet](/themes/architecture/snippets) or [app block](/themes/architecture/sections/section-schema#render-app-blocks).
#### Examples
code:
data:
{}
output:
code:
data:
{}
output:
code:
data:
{}
output:
### section
Deprecated: false
{% section 'name' %}
Renders a [section](/themes/architecture/sections).
#### Examples
code:
{% section 'header' %}
data:
{"cart":{"item_count":2},"request":{"origin":"https://polinas-potent-potions.myshopify.com","page_type":"index"},"routes":{"account_url":"/account","cart_url":"/cart","root_url":"/","search_url":"/search"},"settings":{"accent_icons":"text","cart_type":"notification","inputs_shadow_vertical_offset":4,"predictive_search_enabled":true,"social_facebook_link":"","social_instagram_link":"","social_pinterest_link":"","social_snapchat_link":"","social_tiktok_link":"","social_tumblr_link":"","social_twitter_link":"","social_vimeo_link":"","social_youtube_link":""},"shop":{"customer_accounts_enabled":true,"name":"Polina's Potent Potions"}}
output:
### sections
Deprecated: false
{% sections 'name' %}
Renders a [section group](/themes/architecture/section-groups).
#### Examples
### stylesheet
Deprecated: false
{% stylesheet %}
css_styles
{% endstylesheet %}
CSS styles included in [section](/storefronts/themes/architecture/sections), [block](/storefronts/themes/architecture/blocks), and [snippet](/storefronts/themes/architecture/snippets) files.
#### Examples
## Variable tags
Variable tags enable you to create new Liquid variables.
> Caution:
> Predefined [Liquid objects](/docs/api/liquid/objects) can be overridden by variables with the same name. To make sure that you can access all Liquid objects, make sure that your variable name doesn't match a predefined object's name.
### assign
Deprecated: false
{% assign variable_name = value %}
Creates a new variable.
#### Examples
code:
{%- assign product_title = product.title | upcase -%}
{{ product_title }}
data:
{"product":{"title":"Health potion"}}
output:
HEALTH POTION
### capture
Deprecated: false
{% capture variable %}
value
{% endcapture %}
Creates a new variable with a string value.
#### Examples
code:
{%- assign up_title = product.title | upcase -%}
{%- assign down_title = product.title | downcase -%}
{%- assign show_up_title = true -%}
{%- capture title -%}
{% if show_up_title -%}
Upcase title: {{ up_title }}
{%- else -%}
Downcase title: {{ down_title }}
{%- endif %}
{%- endcapture %}
{{ title }}
data:
{"product":{"title":"Health potion"}}
output:
Upcase title: HEALTH POTION
### decrement
Deprecated: false
{% decrement variable_name %}
Creates a new variable, with a default value of -1, that's decreased by 1 with each subsequent call.
#### Examples
code:
{% decrement variable %}
{% decrement variable %}
{% decrement variable %}
data:
{}
output:
-1
-2
-3
### increment
Deprecated: false
{% increment variable_name %}
Creates a new variable, with a default value of 0, that's increased by 1 with each subsequent call.
#### Examples
code:
{% increment variable %}
{% increment variable %}
{% increment variable %}
data:
{}
output:
0
1
2