What is a Shopify Liquid tag?

Tweet LinkedIn

A Shopify Liquid tag is a special syntax used within Shopify’s templating language, Liquid, to perform specific tasks or logic in a Shopify theme.

Liquid tags are enclosed in curly braces and percent signs: {% %}.

They enable you to control the flow of your templates, render dynamic content, and execute loops or conditionals.

Liquid code is executed on the server side.

If you come from complex languages and want to learn “Liquid” it will be very simple for you to understand it and use it.

On the other hand to an advanced programmer the “Liquid” templating language will look very limited due to the fact that many times you need to write a lot of code to achieve simple things.

How to use Liquid tags?

Tags are wrapped with curly brace percentage delimiters {% %}.

The text within the delimiters doesn’t produce visible output when rendered.

To output a result to screen we use {{ }} without the “%”.

Certain tags can accept parameters.

Some parameters are required, while others are optional.

For instance, the “for” tag can accept parameters such as “limit” to terminate a loop at a specified index.

Example:

{% assign fruits = 'apple,banana,cherry,grape,orange' | split: ',' %}
{% for fruit in fruits limit: 3 -%}
 {{ fruit }}
{%- endfor %}

In this example, the loop will iterate over the fruits array and output the first three items: apple, banana, and cherry.

The “Liquid” tag

The “Liquid” tag was introduced recently to help with writing Liquid code in blocks.

For me this is one of the most used tags since I write most of the logic inside this tag.

Note: Because the tags don’t have delimiters, each tag needs to be on its own line.

Example without the “Liquid” tag:

{% assign product_categories = 'electronics,clothing,home,kitchen,sports' | split: ',' %}
{% assign messages = '' %}
{% for category in product_categories limit: 3 %}
 {% case category %}
  {% when 'electronics' %}
   {% assign messages = messages | append: 'Find the latest in electronics! ' %}
  {% when 'clothing' %}
   {% assign messages = messages | append: 'Check out our stylish clothing! ' %}
  {% when 'home' %}
   {% assign messages = messages | append: 'Discover our home essentials! ' %}
  {% else %}
   {% assign messages = messages | append: 'Explore our diverse categories! ' %}
  {% endcase %}
{% endfor %}

In this example, the loop iterates over the first three items of the “product_categories” array and appends customized messages to the “messages” variable based on the category.

The final “messages” variable will contain the combined messages for the first three categories.

To output:

{{ messages }}

Example with the “Liquid” tag:

{% liquid
 assign product_categories = 'electronics,clothing,home,kitchen,sports' | split: ','
 assign messages = ''
for category in product_categories limit: 3
  case category
   when 'electronics'
    assign messages = messages | append: 'Find the latest in electronics! '
   when 'clothing'
    assign messages = messages | append: 'Check out our stylish clothing! '
   when 'home'
    assign messages = messages | append: 'Discover our home essentials! '
   else
    assign messages = messages | append: 'Explore our diverse categories! '
   endcase
 endfor echo messages
%}

This code snippet performs the same operations as the previous example, but it is encapsulated within the {% liquid %} tags.

Differences between the two:

When using inline Liquid tags you structure your code with individual tags for each operation.

This approach is more verbose and can be easier to read and debug especially for those who are new to Liquid or prefer a clear, step-by-step format.

On the other hand this approach is more cumbersome since you need to open and close the tags many times.

The “Liquid” tag on the other hand allows you to write more compact and streamlined code by combining multiple Liquid statements within a single tag.

This approach reduces the verbosity of your code and can make it look cleaner and more organized.

It is particularly useful for more experienced developers who are comfortable with a denser syntax.

Types of Liquid tags

There are 6 types of liquid tags: variable, conditional, HTML, iteration, syntax, theme.

Variable Tags

In Liquid, variable tags are used to assign and manipulate values within a template.

These tags allow you to create dynamic content by storing data that can be referenced and modified throughout your “Liquid” template.

The “assign” liquid tag

The “assign” liquid tag is used to assign a value to a variable.

This is one of the most common ways to create and manipulate variables in Liquid.

{% assign product_name = 'T-shirt' %}
<p>Product: {{ product_name }}</p>

The variable “product_name” is assigned the value “T-shirt”.

The value of “product_name” is output using {{ product_name }}.

The “capture” liquid tag

The “capture” liquid tag captures a block of Liquid code or content and assigns it to a variable.

This is useful for storing more complex content or multiline text.

{% capture product_description %}
 This is a great product that offers many features and benefits. 
 You will love using it every day!
{% endcapture %}
<p>Description: {{ product_description }}</p>

In the example above the “product_description” variable captures a block of text and the captured content is output using {{ product_description }}.

Conditional tags

Conditional tags evaluate expressions and execute the associated block of code only if the condition is true.

Commonly used conditional tags include “if”, “elsif”, “else”, and “case”.

The “if”, “elsif”, “else” liquid tags

The “if” tag checks a condition and executes the code within its block if the condition is true.

The “elsif” and “else” tags provide additional conditions and a fallback if none of the previous conditions are met.

Example:

{% assign product_price = 50 %}
{% if product_price > 100 %}
 <p>This product is expensive.</p>
{% elsif product_price > 50 %}
 <p>This product is moderately priced.</p>
{% else %}
 <p>This product is affordable.</p>
{% endif %}

If “product_price” is greater than 100, “This product is expensive.” will be displayed.

If “product_price” is greater than 50 but not greater than 100, “This product is moderately priced.” will be displayed.

If “product_price” is 50 or less, “This product is affordable.” will be displayed.

The “case”, “when”, “else” liquid tags

The “case” tag is used for multi-way branching, and it is similar to “switch-case” statements in other programming languages.

The “when” tag specifies different cases to match, and the “else” tag provides a fallback for unmatched cases.

Example:

{% assign product_type = 'health' %}
{% case product_type %}
 {% when 'health' %}
  <p>This is a health potion!</p>
 {% when 'love' %}
  <p>This is a love potion!</p>
 {% else %}
  <p>This is a potion!</p>
{% endcase %}

In the example above:

If “product_type” is ‘health’, “This is a health potion!” will be displayed.

If “product_type” is ‘love’, “This is a love potion!” will be displayed.

If “product_type” is neither ‘health’ nor ‘love’, “This is a potion!” will be displayed.

The “unless” tag

In Liquid, the “unless” tag is used to execute a block of code only if a specified condition is false.

It works as the inverse of the “if” tag, making it useful for simplifying logic where you want to run code only when certain conditions are not met.

Example:

{% assign product_in_stock = false %}
{% unless product_in_stock %}
 <p>Sorry, this product is currently out of stock.</p>
{% endunless %}

If “product_in_stock” is false, the message “Sorry, this product is currently out of stock.” will be displayed.

If “product_in_stock” is true nothing will be displayed, as the condition inside the “unless” tag is not met.

You can also combine the “unless” tag with other tags to create more complex logic.

Here’s an example:

{% assign product_price = 30 %}
{% assign product_on_sale = false %}
{% unless product_price > 50 or product_on_sale %}
 <p>This product is not on sale and costs less than $50.</p>
{% endunless %}

The message “This product is not on sale and costs less than $50.” will be displayed only if “product_price” is not greater than 50 and “product_on_sale” is false.

By using the unless tag you can effectively manage scenarios where you want to execute code only when certain conditions are not true thus adding flexibility and readability to your Liquid templates.

Syntax tags

Syntax tags in Liquid are special tags that control the code processing and rendering of your templates. 

They help in organizing, displaying, and manipulating content in various ways.

The “comment” Liquid tag

The “comment” tag is used to insert comments into your Liquid code.

Anything inside the “comment” tag will not be rendered in the output HTML.

This is useful for adding notes and explanations within your code that won’t be visible to the end user.

Example:

{% comment %}
  This is a comment and will not be rendered in the HTML output.
{% endcomment %}

In the example above nothing will be rendered to screen.

{% comment %}
  This section is for featured products only.
{% endcomment %}
<p>Featured Products:</p>

In the example above, the comment explains the purpose of the code section, but it won’t appear in the rendered HTML.

Only the “<p>Featured Products:</p>” will be rendered to screen.

The “echo” Liquid tag

The “echo” liquid tag is used to output the value of a variable or expression.

It is similar to using {{ }} but allows for more complex operations and is often used in conjunction with filters and other Liquid logic.

Syntax:

{% echo variable %}

Example:

{% assign product_name = 'Awesome Widget' %}
{% echo product_name %}

In this example, “product_name” will be output where the “echo” tag is used.

As you see “echo” must be used inside the “{%%}” and not inside the “{{}}” since the last one has the same function as “echo”, outputs something to screen.

The “liquid” tag

The “liquid” tag allows you to write multiple Liquid statements inside a single tag and block. 

This can make your code more concise and organized.

It is particularly useful for combining several Liquid operations in one place.

Example:

{% liquid
  assign product_name = 'Awesome Widget'
  echo product_name
%}

Example:

In this example, the liquid tag combines variable assignment and conditional logic in a single block.

{% liquid
  assign product_price = 50
  if product_price > 30
    echo 'This product is expensive.'
  else
    echo 'This product is affordable.'
  endif
%}

The “raw” Liquid tag

The “raw” tag is used to include raw Liquid code in your templates without processing it.

This is useful when you want to display Liquid code examples or prevent certain sections of code from being interpreted by the Liquid engine.

In short it outputs Liquid code as text instead of rendering it.

Example:

{% raw %}
  {% assign product_name = 'Awesome Widget' %}
{% endraw %}

In this example, the content inside the raw tags will be displayed as plain text showing the Liquid code without executing it:

{% raw %}
  {% if user_logged_in %}
    Welcome back, {{ user_name }}!
  {% endif %}
{% endraw %}

Iteration tags

Iteration tags in Liquid are used to loop through collections of items, such as arrays or objects, allowing you to display each item in the collection.

The “for” Liquid tag

Renders an expression for every item in an array.

You can do a maximum of 50 iterations with a for loop. If you need to iterate over more than 50 items, then you need to use the paginate tag to split the items over multiple pages.

Syntax:

{% for variable in array %}
  <!-- Code to execute for each item -->
{% endfor %}

In the example below the “for” tag iterates over the fruits array and each fruit is output as a list item in an unordered list.

Example:

{% assign fruits = 'apple,banana,cherry' | split: ',' %}
<ul>
  {% for fruit in fruits %}
    <li>{{ fruit }}</li>
  {% endfor %}
</ul>

You can limit the number of iterations on a for loop or set an offset to skip items.

Syntax:

{% for variable in array limit: number %}
  expression
{% endfor %}

In the example below the loop starts from the third item (offset: 2) and displays the next five products (limit: 5):

Example:

{% for product in products limit: 5 offset: 2 %}
  <p>{{ product.name }}</p>
{% endfor %}

You can iterate over a collection in reverse order with “reversed” parameter.

Example:

{% for product in products reversed %}
  <p>{{ product.name }}</p>
{% endfor %}

In Liquid, you can iterate over a range of numbers using the “for” tag.

This is useful when you need to execute a block of code a specific number of times or when working with numerical sequences.

Syntax:

{% for variable in (start..end) %}
  <!-- Code to execute for each item -->
{% endfor %}

“start”: The beginning number of the range.

“end”: The ending number of the range.

“variable”: The variable name used to represent the current number in the loop.

You can define the range using literal numbers.

Example:

<ul>
  {% for i in (1..5) %}
    <li>Item {{ i }}</li>
  {% endfor %}
</ul>

In the example above the liquid loop iterates from 1 to 5.

Each iteration outputs a list item with the current number.

You can also use variables to define the range.

Example:

{% assign start = 3 %}
{% assign end = 7 %}

<ul>
  {% for i in (start..end) %}
    <li>Step {{ i }}</li>
  {% endfor %}
</ul>

In this example the loop iterates from the value of start (3) to the value of end (7).

Each iteration outputs a list item with the current number.

The “else” Liquid tag

The “else” tag can be used within a for loop to provide fallback content if the array or object being iterated over is empty.

Syntax:

{% for item in array %}
  <!-- Code to execute for each item -->
{% else %}
  <!-- Code to execute if the array is empty -->
{% endfor %}

Example:

{% assign fruits = '' | split: ',' %}
<ul>
  {% for fruit in fruits %}
    <li>{{ fruit }}</li>
  {% else %}
    <li>No fruits available.</li>
  {% endfor %}
</ul>

Since the above “fruits” array is empty, the code after {% else %} will be executed and the output will be “No fruits available.”.

The “break” Liquid tag

The “break” tag exits the loop immediately when it is encountered.

This is useful for stopping the loop when a certain condition is met.

Syntax:

{% for item in collection %}
  {% if condition %}
    {% break %}
  {% endif %}
  <!-- Code to execute for each item -->
{% endfor %}

Example:

{% assign numbers = '1,2,3,4,5' | split: ',' %}
<ul>
  {% for number in numbers %}
    {% if number == '3' %}
      {% break %}
    {% endif %}
    <li>{{ number }}</li>
  {% endfor %}
</ul>

In this example, the loop will stop when the number “3” is encountered, so only “1” and “2” will be displayed.

The “continue” Liquid tag

The “continue” tag skips the rest of the current iteration and moves to the next item in the loop.

This is useful for skipping over certain items based on a condition.

Syntax:

{% for item in array %}
  {% if condition %}
    {% continue %}
  {% endif %}
  <!-- Code to execute for each item -->
{% endfor %}

Example:

{% assign numbers = '1,2,3,4,5' | split: ',' %}
<ul>
  {% for number in numbers %}
    {% if number == '3' %}
      {% continue %}
    {% endif %}
    <li>{{ number }}</li>
  {% endfor %}
</ul>

In this example, the loop will skip the number “3”, so “1”, “2”, “4”, and “5” will be displayed.

Combining these tags allows for sophisticated control over loop execution making it possible to handle complex logic and edge cases within your Liquid code.

Combined example:

{% assign numbers = (1..10) %}
{% assign threshold = 8 %}
<ul>
  {% for number in numbers %}
    {% if number > threshold %}
      {% break %}
    {% endif %}
    {% if number == 5 %}
      {% continue %}
    {% endif %}
    <li>{{ number }}</li>
  {% else %}
    <li>No numbers available.</li>
  {% endfor %}
</ul>

In the example above the loop breaks when the “number” exceeds the “threshold” (8), so only numbers 1 to 8 are considered.

The number 5 is skipped due to the “continue” tag.

If the “numbers” array were empty, the “else” block would display “No numbers available.”

By using “for”, “else”, “break”, and “continue” tags in Liquid you can gain fine-grained control over iteration in your templates.

These tags enable you to handle empty collections gracefully with “else”, exit loops early with “break” and skip specific iterations with “continue”.

The “cycle” tag in Liquid

The “cycle” tag in Liquid is used to loop through a group of strings and output them one at a time for each iteration of a “for” loop.

This tag is particularly useful for creating patterns such as alternating classes for table rows or repeating a set of values in a consistent sequence.

The “cycle” tag must be used inside a “for” loop.

You can define a group of strings separated by commas and the “cycle” tag will output each string in turn for each iteration of the loop.

Syntax:

{% cycle 'value1', 'value2', 'value3' %}

A common use case for the cycle tag is to apply alternating classes to rows in a table, helping to distinguish between odd and even rows for better readability.

Example:

{% assign products = 'Product 1,Product 2,Product 3,Product 4,Product 5' | split: ',' %}
<table>
 {% for product in products %}
  <tr class="{% cycle 'odd', 'even' %}">
   <td>{{ product }}</td>
  </tr>
 {% endfor %}
</table>

In this example the “cycle” tag alternates the class attribute between “odd” and “even” for each row in the table.

This helps to visually differentiate between rows.

You can use the “cycle” tag to repeat a set of values in a loop.

Example:

{% assign colors = 'red,green,blue' | split: ',' %}
<ul>
 {% for color in colors %}
  <li style="color: {% cycle 'red', 'green', 'blue' %};">
   {{ color }}
  </li>
 {% endfor %}
</ul>

In this example the “cycle” tag cycles through the colors “red”, “green”, and “blue” for each list item, applying the corresponding style.

The “cycle” tag in Liquid is a powerful tool for creating predictable patterns within loops.

By alternating between a set of values you can easily apply styles, repeat sequences, and manage complex iterations.

You can also create custom patterns with the cycle tag.

Example:

{% assign items = 'Item 1,Item 2,Item 3,Item 4,Item 5,Item 6' | split: ',' %}
<ul>
 {% for item in items %}
  <li>{{ item }} - {% cycle 'Alpha', 'Beta', 'Gamma' %}</li>
 {% endfor %}
</ul>

In the example above the “cycle” tag outputs “Alpha”, “Beta”, and “Gamma” in sequence for each item in the list

Theme tags

Theme tags in Liquid are special tags used to include assets and dynamic content specific to Shopify themes.

These tags help in organizing and managing theme-specific resources ensuring that they are loaded and executed correctly.

The “javascript” Liquid tag

The “javascript” tag is used to include JavaScript code directly within a section file.

This tag is necessary when your section or app block needs to be installed on multiple themes or stores as it ensures that the required JavaScript is bundled and executed correctly with the section.

Limitations

Each section or app block can have only one {% javascript %} tag.

Is not possible to add Liquid code inside the “javascript” tag.

Liquid code is not rendered inside {% javascript %} tags due to the fact that Liquid code is executed server side.

Including Liquid code within these tags will cause syntax errors.

You must use this tag for section-specific JavaScript.

For general theme JavaScript used globally, include the code in the theme’s assets directory and request it like in this tutorial: How to add a custom javascript file to shopify in liquid?

Syntax:

{% javascript %}
 javascript_code
{% endjavascript %}

Example:

{% javascript %}
  document.addEventListener('DOMContentLoaded', function() {
    const section = document.querySelector('.my-section');
    if (section) {
      section.style.backgroundColor = 'lightblue';
    }
  });
{% endjavascript %}

In the example above the JavaScript code runs when the DOM content is loaded.

It selects an element with the class “.my-section” and changes its background color to light blue.

The “stylesheet” Liquid tag

The stylesheet tag in Liquid is used to include CSS styles directly within a section file.

This tag is particularly useful when your section or app block needs to be installed on multiple themes or stores ensuring that the required CSS is bundled and executed correctly with the section.

Limitations

Each section or app block can have only one {% stylesheet %} tag.

Liquid code is not rendered inside {% stylesheet %} tags due to the fact that Liquid code is executed server side.

Including Liquid code within these tags will cause syntax errors.

You must use this tag for section-specific CSS.

For general theme CSS, include the styles in the theme’s assets directory and request them like in this tutorial: How to add a custom css file to Shopify in Liquid?

Syntax:

{% stylesheet %}
  css_styles
{% endstylesheet %}

Example:

Let’s say you have a section file that requires specific styles.

You can use the {% stylesheet %} tag to include those styles directly within the section.

<div class="custom-section">
  <h2>{{ section.settings.heading }}</h2>
  <p>This is a custom section with specific styles.</p>
</div>
{% stylesheet %}
  .custom-section {
    background-color: lightblue;
    padding: 20px;
    border-radius: 5px;
  }

  .custom-section h2 {
    color: #333;
  }
{% endstylesheet %}

In the example above the “custom-section” div contains content that is styled with the CSS included in the “{% stylesheet %}” tag.

The CSS styles within the tag are specific to the section, ensuring they are applied correctly when the section is installed on different themes or stores.

The “layout” Liquid tag

The “layout” tag in Liquid is used to specify the layout file that a template should extend or inherit from.

By default, the “theme.liquid” layout is used.

The “layout” tag allows you to specify an alternative layout.

Layout files are stored in the layouts directory of your Shopify theme and typically include the “theme.liquid” and “password.liquid” files, which serves as the main layout for most pages.

Other layout files can be created for specific purposes, such as different layouts for blogs, products or custom pages.

When you create a template that should extend a specific layout, you use the layout tag to define which layout to use.

The layout tag should be placed at the top of your template file.

Syntax:

{% layout 'layout_name' %}

Example:

{% layout 'theme' %}

<h1>Custom Page</h1>
<p>This is a custom page that uses the main theme layout.</p>

In the example above the “layout” tag specifies that this template should use the theme layout file.

The “render” tag

The “render” tag in Liquid is used to include and execute a snippet within the current section.

This is especially useful for reusing snippets and partials across different parts of a Shopify theme, promoting modular and maintainable code.

Syntax:

{% render 'snippet_name' %}

An in depth tutorial about the “render” tag can be found here: “What is Shopify “render” and how to use it?”

Conclusion

In this article, we have explored various Liquid tags that are essential for building dynamic and maintainable Shopify themes.

Each tag serves a specific purpose contributing to the modularity, flexibility and functionality of your theme.

​​By mastering these Liquid tags you can create sophisticated and efficient Shopify themes that are easy to maintain and extend.

Each tag adds a layer of functionality and control allowing you to build themes that are not only visually appealing but also highly functional and adaptable to various needs and contexts.

Understanding and leveraging these tags effectively will enable you to deliver high-quality, customizable, and scalable e-commerce solutions ensuring a better user experience and streamlined theme development process.