# Tags

Source: https://developers.swell.is/storefronts/swell-liquid-reference/liquid-tags

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

### Conditional

Conditional tags control if and when expressions are rendered.

---

#### if

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.

**Syntax**

```liquid
{% if condition %}
  expression
{% endif %}
```

- `condition`: The condition to evaluate.
- `expression`: The expression to render when the condition is met.

#### elsif

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`.

**Example**

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

#### else

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.

**Syntax**

```liquid
{% else %}
  expression
```

#### unless

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.

**Syntax**

```liquid
{% unless condition %}
  expression
{% endunless %}
```

- `condition`: The condition to evaluate.
- `expression`: The expression to render unless the condition is met.

#### case

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.

**Syntax**

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

- `variable`: The variable used to evaluate the case statement.
- `value_one`: A specific value to match against.
- `value_two`: A specific value to match against.
- `expression`: The expression to render when the value is matched.

### HTML

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

---

#### form

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](https://developers.swell.is/storefronts/proxima-app), to coincide with their intended functionality. Refer to the app's documentation for specific forms that are available in its environment.

**Syntax**

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

- `type`: The specific type of form to render.
- `content`: Content rendered inside the `<form>` HTML tag.

**Optional tag parameters**

- `return_to`: URL to redirect the page to after the form is successfully submitted.

**HTML attributes**

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

**Example**

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

#### style

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.

**Syntax**

```liquid
{% style %}
  css_rules
{% endstyle %}
```

- `css_rules`: The CSS rules to evaluate at run-time.

### Iteration

Iteration tags are used to repeatedly evaluate blocks of code.

---

#### for

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

**Syntax**

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

- `variable`: A variable to assign for each item in the array.
- `array`: The array or collection to iterate over.
- `expression`: The expression to render for each iteration.

**Optional tag parameters**

- `limit`: The maximum number of iterations.
- `offset`: A number of iterations to start from.
- `reversed`: Reverse the order of iteration.

**Range iteration**

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

**Syntax**

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

**forloop object**

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

**Properties**

- `first` (boolean): Indicates the current iteration is the **first** one.
- `index` (number): The 1-based index of the current iteration.
- `index0` (number): The 0-based index of the current iteration.
- `last` (boolean): Indicates the current iteration is the **last** one.
- `length` (number): The total number of iterations.
- `parentloop` (forloop): The parent `forloop` object, if nested inside another `for` loop.
- `rindex` (number): The 1-based index of the current iteration in reverse order.
- `rindex0` (number): The 0-based index of the current iteration in reverse order.

**Example**

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

#### else

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.

**Syntax**

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

- `variable`: A variable to assign for each item in the array.
- `array`: The array or collection to iterate over.
- `expression`: The expression to render for each iteration.

#### break

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

**Syntax**

```liquid
{% break %}
```

**Example**

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

#### continue

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.

**Syntax**

```liquid
{% continue %}
```

**Example**

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

#### cycle

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

**Syntax**

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

**Example**

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

#### tablerow

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.

**Syntax**

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

- `variable`: A variable to assign for each item in the array.
- `array`: The array or collection to iterate over.
- `expression`: The expression to render for each iteration.

**Example**

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

**Optional tag parameters**

- `cols`: The number of columns the table should have.
- `limit`: The maximum number of iterations.
- `offset`: A number of iterations to start from.

**Range iteration**

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

**Syntax**

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

**tablerowloop object**

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

**Properties**

- `col` (number): The 1-based index of the current column.
- `col0` (number): The 0-based index of the current column.
- `col_first` (boolean): Indicates the current column is the **first** one.
- `col_last` (boolean): Indicates the current column is the **last** one.
- `first` (boolean): Indicates the current iteration is the **first** one.
- `index` (number): The 1-based index of the current iteration.
- `index0` (number): The 0-based index of the current iteration.
- `last` (boolean): Indicates the current iteration is the **last** one.
- `length` (number): The total number of iterations.
- `rindex` (number): The 1-based index of the current iteration in reverse order.
- `rindex0` (number): The 0-based index of the current iteration in reverse order.
- `row` (number): The 1-based index of the current row.

#### paginate

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.

**Syntax**

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

- `collection`: The collection object or array to paginate with
- `limit`: The maximum number of items to include per page, up to 1,000.
- `item`: The the item of the `for` loop being iterated inside the `paginate` tag.
- `for_content`: The content of each `for` loop iteration.

**Example**

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

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

**Optional tag parameters**

- `window_size`: The number of pages that should be displayed in pagination navigation.

### Syntax

Syntax tags effect how Liquid is processed and rendered.

---

#### comment

Adds non-rendered text to the code.

**Syntax**

```liquid
{% comment %}
  content
{% endcomment %}
```

- `content`: The content of the comment.

**Inline comments**

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

**Example**

```liquid
{% # a single line comment %}

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

Inline comments can also be used inside Liquid tags.

**Example**

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

#### echo

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

**Syntax**

```liquid
{% liquid
  echo expression
%}
```

- `expression`: The expression to be rendered.

#### liquid

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.

**Syntax**

```liquid
{% liquid
  expression
%}
```

- `expression`: The expression to be evaluated.

#### raw

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

**Syntax**

```liquid
{% raw %}
  expression
{% endraw %}
```

- `expression`: The expression to output without being evaluated.

### Theme

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

---

#### include

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.*

**Syntax**

```liquid
{% include 'component' %}
```

- `file_name`: The name of the component file (snippet) to render, without the `.liquid` extension.

#### javascript

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

**Syntax**

```liquid
{% javascript %}
  code
{% endjavascript %}
```

- `code`: The JavaScript code to be executed at run-time.

#### layout

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

**Syntax**

```liquid
{% layout 'name' %}
```

- `name`: The name of the layout file to use, or `none` for no layout.

#### render

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

**Syntax**

```liquid
{% render 'file_name' %}
```

- `file_name`: The name of the component file (snippet) to render, without the `.liquid` extension.

**Passing variables**

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

**Example**

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

**Render** **`for`**

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

**Example**

```liquid
{% 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.

**Example**

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

#### section

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.

**Syntax**

```liquid
{% section 'name' %}
```

- `name`: The name of the section file to render.

#### sections

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.

**Syntax**

```liquid
{% sections 'name' %}
```

- `name`: The name of the section group file to render.

### Variable

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

---

#### assign

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.

**Syntax**

```liquid
{% assign variable = value %}
```

- `variable`: The name of the variable being created or updated.
- `value`: The value to assign to the variable.

**Example**

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

{{ product_name }}
```

#### capture

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.

**Syntax**

```liquid
{% capture variable %}
  value
{% endcapture %}
```

- `variable`: The name of the variable being created or updated.
- `value`: The value to assign to the variable.

#### decrement

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

**Syntax**

```liquid
{% decrement variable %}
```

- `variable`: The name of the variable being decremented.

#### increment

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

**Syntax**

```liquid
{% increment variable %}
```

- `variable`: The name of the variable being incremented.

### Shopify compatibility

Tags implemented strictly to enable compatibility with Shopify themes.

---

#### stylesheet

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.

> **Warning:** Liquid code is not rendered inside the {% stylesheet %} tag.

**Syntax**

```liquid
{% stylesheet %}
  css_rules
{% endstylesheet %}
```

- `css_rules`: The CSS styles to render for the section, block, or component.