Tags

Tags are logical code that dynamically control the output of theme templates.

Conditional tags control if and when expressions are rendered.

Executes a block of code only if a specified condition evaluates to truthy. It allows for conditional rendering of content based on variables or expressions.

{% if condition %}
  expression
{% endif %}

Adds additional conditions to an if or unless block, executing its code only if previous conditions are falsy and its own condition is truthy. This tag must follow an if or another elsif and precede any else.

{% if product.sale %}
  On sale
{% elsif price < 10 %}
  Under $10
{% endif %}

Provides a fallback block of code that executes if all preceding if and elsif conditions in the structure are falsy. This tag is optional and can only appear once at the end of an if or unless block.

{% else %}
  expression

Executes a block of code only if a specified condition evaluates to falsy, acting as the inverse of the if tag. Like if, it can be combined with elsif and else for more complex flows.

{% unless condition %}
  expression
{% endunless %}

Creates a switch statement that compares a variable against multiple values, executing the corresponding when block for the first match. Each when can check one or more values, and an optional else handles unmatched cases.

{% case variable %}
  {% when value_one %}
    expression
  {% when value_two %}
    expression
  {% else %}
    expression
{% endcase %}

HTML tags are used to output HTML with Swell-specific attributes.

Renders an HTML <form> tag to submit <input> and other form values to a specific endpoint. Forms are defined by each storefront app, such as Proxima, to coincide with their intended functionality. Refer to the app's documentation for specific forms that are available in its environment.

{% form 'type' %}
  content
{% endform %}

Optional tag parameters

HTML attributes

You may add additional named parameters to the form tag in order to attach HTML attributes to the rendered form.

{% form 'type', id: 'custom-id', class: 'custom-class', data-example: 'value' %}
  <!-- content -->
{% endform %}

Renders a <style> tag with attributes required by the Swell Theme Editor.

You may reference theme color settings, and other global values within the style tag. If your theme includes plain <style> tags without this syntax, then Liquid values may not update as expected within the editor.

{% style %}
  css_rules
{% endstyle %}

Iteration tags are used to repeatedly evaluate blocks of code.

Iterates over an array or a range of numbers, executing the enclosed code block for each item.

{% for variable in array %}
  expression
{% endfor %}

Optional tag parameters

Range iteration

Instead of iterating over array items, specify a numeric range in the format of (number..number).

{% for num in (1..3) %}
  {{ num }}
{% endfor %}

forloop object

Contains information about the current for iteration, from within the expression.

Properties

{% for product in products %}
  Product #{{ forloop.index }}
  {% if forloop.last %}
    There are {{ forloop.length }} products
  {% endif %}
{% endfor %}

When used within a for or tablerow loop, executes its code block if the iterated collection is empty. It provides a fallback for no results.

{% for variable in array %}
  expression
{% else %}
  expression
{% endfor %}

Terminates the enclosing for or tablerow loop immediately when encountered. It exits the loop without processing remaining iterations.

{% break %}

{% for num in (1..3) -%}
  {% if num > 1 %}
    {% break %}
  {% else %}
    {{ num }}
  {% endif %}
{% endfor %}

Skips the rest of the current iteration in a for or tablerow loop and proceeds to the next one. It jumps to the next loop cycle.

{% continue %}

{% for num in (1..3) -%}
  {% if num == 2 %}
    {% continue %}
  {% else %}
    {{ num }}
  {% endif %}
{% endfor %}

Outputs values from a provided list in sequence, repeating as needed during iterations. It accepts a group name for independent cycling across multiple uses.

{% cycle 'string', 'string', ... %}

{% for num in (1..3) -%}
  {% cycle 'one', 'two', 'three' %}
{% endfor %}

Iiterates over a collection like for, but formats output into an HTML table row with cells.

A tablerow tag should be enclosed in a <table> HTML element.

{% tablerow variable in array %}
  expression
{% endtablerow %}

<table>
  {% tablerow product in products cols: 2 %}
    {{ product.name }}
  {% endtablerow %}
</table>

Optional tag parameters

Range iteration

Instead of iterating over array items, specify a numeric range in the format of (number..number).

{% tablerow num in (1..3) %}
  {{ num }}
{% endtablerow %}

tablerowloop object

Contains information about the current for iteration, from within the expression.

Properties

Splits a collection object into pages and provides information about the current page, items, and navigation links. Pagination is typically used with collections of records, such as products, categories, blogs, customer addresses, etc.

A for loop should be used inside a paginate tag to iterate over the collection's items.

{% paginate collection by limit %}
  {% for item in collection %}
    for_content
  {% endfor %}
{% endpaginate %}

{% paginate category.products by 15, window_size: 3 %}
  {% for product in category.products %}
    {{ product.name }}
  {% endfor %}

  {{ paginate | default_pagination }}
{% endpaginate %}

Optional tag parameters

Syntax tags effect how Liquid is processed and rendered.

Adds non-rendered text to the code.

{% comment %}
  content
{% endcomment %}

Inline comments

You may use a hash # character to prevent the following expression from being evaluated inside any tag.

{% # a single line comment %}

{% # for num in (1..3) -%}
  {{ num }}
{% # endfor %}

Inline comments can also be used inside Liquid tags.

{% liquid
  # this is an inline comment
  assign num_products = products.length
%}

Renders the value of an expression directly to the template. It functions similarly to the {{ }} output tag but in a procedural context.

{% liquid
  echo expression
%}

Encloses a block of procedural Liquid code, allowing commands like echo, if, and assign on separate lines. It supports multi-line scripting without needing individual {% %} tags for each statement.

{% liquid
  expression
%}

Prevents the enclosed content from being parsed as Liquid code, outputting it as plain text.

{% raw %}
  expression
{% endraw %}

Theme tags are used to control output for layouts, sections and blocks.

Renders a component (snippet) file, allowing access to parent template variables. The component has access to variables in the parent scope.

Note: include deprecated in favor of the render tag for better performance.

{% include 'component' %}

Encloses JavaScript code within layouts, sections, blocks, or components. It generates a <script> tag for execution in the theme.

{% javascript %}
  code
{% endjavascript %}

Specifies which layout file to use for the current template from the layouts/ folder. Without a name, it defaults to theme.liquid.

{% layout 'name' %}

Renders a snippet or app block, isolating variables from the parent template. It supports passing variables as parameters for controlled access.

{% render 'file_name' %}

Passing variables

You may pass variables as named parameters to the component, which become available within its scope when rendered.

{% render 'file_name', variable: value %}

Render for

Use the for parameter to render a component for every item in a collection or array.

{% render 'file_name' for array as item %}

Render with

Use the with parameter to pass an entire object to the component, assigned as a variable with the name specified.

{% render 'file_name' with object as name %}

Renders a section file from the sections/ folder. It integrates customizable sections into templates. This renders a section statically, such that its settings are not editable in the Swell Theme Editor.

{% section 'name' %}

Renders a group of sections as part of a theme's layout. It allows dynamic inclusion of multiple sections grouped by name in the layout.

Place the sections tag where you want the section group to be rendered.

{% sections 'name' %}

Variable tags are used to assign and modify variables used throughout theme logic.

Creates a new variable or updates an existing one with the result of an expression. It supports assigning values like strings, numbers, arrays, or outputs from filters.

{% assign variable = value %}

{% assign product_name = product.name | upcase %}

{{ product_name }}

Assigns the rendered content between its tags to a variable, without outputting it directly. The captured variable can then be used or manipulated elsewhere in the template.

{% capture variable %}
  value
{% endcapture %}

Decreases a number variable by 1 and outputs the new value. If the variable doesn't exist, it starts at -1 before decrementing.

{% decrement variable %}

Increases a number variable by 1 and outputs the new value. If the variable doesn't exist, it starts at -1 before incrementing.

{% increment variable %}

Tags implemented strictly to enable compatibility with Shopify themes.

Encloses CSS rules within sections, blocks, or components (snippets). Its contents are combined with other stylesheet output on a page and rendered as combined optimized output.

{% stylesheet %}
  css_rules
{% endstylesheet %}