Swell Liquid

The following are logical and comparison operators used within conditional tags.

Numerical operators such as + and - are not supported. Instead, you would use the mathematical filters such as {{ a | plus: b }} and {{ a | plus: b }}. See the Math filter section for more details.

Tags are surrounded by {% ... %} delimiters and are always closed with a matching end tag.

{% if account %}
  Hello, {{ account.name }}
{% endif %}

Filters are used to modify output or assignment of a variable, separate by a pipe | character. They can take one or more positional or named arguments.

{{ product.price | money }}

Liquid templates are formatted for readability, however it can affect the HTML output in undesirable ways. Use a hyphen - character on either or both sides of any tag to cause Liquid to strip whitespace on the left and right sides of the tag.

{%- if category.products.size > 0 -%}
  ...
{%- endif -%}

Also note, each tag outputs a trailing newline \n character, however adding a hyphen to the end of the tag will strip the newline from output.

{% assign author = "emmett" -%}
{{ author }}

The following are supported conditional tags for output control.

See the Conditional tags section for more details.

The following are tags used to iterate through array and collection values.

See the Iteration tags section for more details.

The following are tags to control how Liquid is processed and rendered.

See the Syntax tags section for more details.

See the Variable tags section for more details.

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 %}

Filters are used to modify Liquid output.

Array filters are used to modify arrays.

Removes empty values from an array.

{{ array | compact }}

Combines two arrays by concatenating them.

{{ array1 | concat: array2 }}

Returns the first object in an array for which the queried attribute has the given value or nil if no match.

{{ array | find: 'property', 'value' }}

Returns the first object in an array for which the given expression evaluates to true or nil if no item satisfies the expression.

{{ array | find_exp: 'item', 'item.property == value' }}

Returns the 0-based index of the first object in an array for which the queried attribute has the given value or nil if no match.

{{ array | find_index: 'property', 'value' }}

Returns the 0-based index of the first object in an array for which the given expression evaluates to true or nil if no item satisfies the expression.

{{ array | find_index_exp: 'item', 'item.property == value' }}

Returns the first element of an array.

{{ array | first }}

Dot notation

You can use the first filter with dot notation inside a tag.

{% assign first_item = array.first %}

Groups array items by a common attribute.

{{ array | group_by: 'property' }}

The group_by_exp filter groups an array's items using a Liquid expression.

{{ array | group_by_exp: 'item', 'item.property == value' }}

Returns true if an item exists in an array for which the queried attribute has the given value or false otherwise.

{{ array | has: 'property', 'value' }}

Returns true if an item exists in an array for which the given expression evaluates to true or false if no item satisfies the expression.

{{ array | has_exp: 'item', 'item.property == value' }}

Joins elements of an array into a string with a separator.

{{ array | join }}

You can also use a custom separator for joined items.

{{ array | join: ', ' }}

Returns the last element of an array.

{{ array | last }}

Dot notation

You can use the last filter with dot notation inside a tag.

{% assign last_item = array.last %}

Creates an array of values by extracting the values of a named property from another object.

{{ array | map: 'property' }}

Creates an array excluding objects with a given property value or excluding truthy values by default if no property is given.

{{ array | reject: 'property', 'value' }}

Creates an array excluding objects for which the given expression evaluates to true.

{{ array | reject_exp: 'item', 'item.property == value' }}

Reverses the order of an array.

{{ array | reverse }}

Returns the number of items in an array.

{{ array | size }}

Dot notation

You can use the size filter with dot notation inside a tag.

{% assign count = array.size %}

Sorts elements of an array.

{{ array | sort }}

You can also sort the array by an item's property.

{{ array | sort: 'property' }}

Sorts elements of an array in a natural order.

{{ array | sort_natural }}

You can also sort the array by an item's property.

{{ array | sort_natural: 'property' }}

Returns the sum of all elements in an array.

{{ array | sum }}

You can also specify a property to sum object values.

{{ array | sum: 'property' }}

Removes duplicate elements from an array.

{{ array | uniq }}

Filters an array based on a matching attribute value.

{{ array | where: 'property', 'value' }}

Filters used to retrieve theme or object related URLs for rendering.

Generates a URL for a theme asset file, such as scripts, or stylesheets. It takes a filename and returns the full path to the asset hosted on the store's CDN.

If you're referencing an image asset, use asset_img_url.

{{ 'main.js' | asset_url }}

Generates a URL for an image file stored in the theme's assets directory. It accepts optional parameters like size to specify image dimensions or formats, returning the full CDN-hosted path.

{{ 'image.png' | asset_img_url }}

Image sizes

You may pass a size parameter to resize the image accordingly. Specify either [width]x, x[height], or both [width]x[height]. You may also specify one of the named sizes below.

{{ 'image.png' | asset_img_url: 'large' }}

{{ 'image.png' | asset_img_url: 'x480' }}

{{ 'image.png' | asset_img_url: '480x' }}

{{ 'image.png' | asset_img_url: '480x480' }}

Generates an HTML <img> tag for an image, using its URL or asset path. It supports optional parameters like alt, class, or width/height for customizing the tag's attributes.

Commonly used in combination with image_url.

{{ product | image_url: width: 250 | image_tag: attribute: 'value' }}

Returns the URL for an image, either from an object such as product or file. It can accept width and height parameter to specify its size.

{{ product | image_url: width: 250, height: 350 }}

Country flags

You may pass a string representing a locale and this filter will return an SVG representing that country's flag.

{{ store.locale | image_url }}

Cart filters are used to retrieve or modify details of a shopping cart.

Returns the total quantity of a specific product variant in the cart. It takes a variant ID as input and outputs the sum of quantities across all matching cart line items.

{{ cart | item_count_for_variant: variant_id }}

Color filters are used to mofy and output color values for CSS styling.

Calculates the brightness difference between two colors, returning a value between 0 and 255. It takes two color values (e.g., hex, RGB) as inputs.

{{ '#57349B' | brightness_difference: '#FFE5F8' }}

Returns the perceived brightness of a color on a scale from 0 (black) to 255 (white). It accepts a color value like hex or RGB.

{{ '#57349B' | color_brightness }}

Calculates the contrast ratio between two colors, returning a value between 1 and 21. It takes two color values as inputs, useful for accessibility checks.

{{ '#57349B' | color_contrast: '#FFE5F8' }}

Darkens a color by a specified percentage (0 to 100). It takes a color value and a percentage as inputs, returning the darkened color in the same format.

{{ '#57349B' | color_darken: 25 }}

Reduces a color’s saturation by a specified percentage (0 to 100). It takes a color value and a percentage, returning the desaturated color.

{{ '#57349B' | color_desaturate: 25 }}

Calculates the perceptual difference between two colors using the CIEDE2000 algorithm, returning a value between 0 and 100. It takes two color values as inputs.

{{ '#57349B' | color_difference: '#FFE5F8' }}

Extracts a specific component (e.g., red, green, blue, hue, saturation, lightness) from a color. It takes a color value and the component name as inputs.

{{ '#57349B' | color_extract: 'red' }}

Color components

Lightens a color by a specified percentage (0 to 100). It takes a color value and a percentage, returning the lightened color in the same format.

{{ '#57349B' | color_lighten: 25 }}

Blends two colors by a specified percentage (0 to 100). It takes two color values and a percentage, returning the mixed color.

{{ '#57349B' | color_mix: '#FFE5F8', 50 }}

If one color has an alpha component and the other does not, the alpha component of 1.0 will be assumed for the color without alpha.

{{ 'rgba(87, 52, 155, 0.50)' | color_mix: '#FFE5F8', 50 }}

Adjusts a specific color component (e.g., red, hue, lightness) by a given value. It takes a color, component name, and adjustment value as inputs.

{{ '#57349B' | color_modify: 'blue', 255 }}

Color components

Increases a color’s saturation by a specified percentage (0 to 100). It takes a color value and a percentage, returning the saturated color.

{{ '#57349B' | color_saturate: 25 }}

Converts a color (e.g., RGB, HSL) to its hexadecimal representation. It takes a color value and returns a hex string (e.g., #FFFFFF).

{{ 'rgb(87, 52, 155)' | color_to_hex }}

Converts a color (e.g., hex, RGB) to its HSL representation. It takes a color value and returns a string like hsl(360, 100%, 50%).

{{ '#57349B' | color_to_hsl }}

Converts a color to the OKLCH color space, which is perceptually uniform. It takes a color value and returns a string like oklch(0.5, 0.2, 360).

{{ '#57349B' | color_to_oklch }}

Converts a color (e.g., hex, HSL) to its RGB representation. It takes a color value and returns a string like rgb(255, 255, 255).

{{ '#57349B' | color_to_rgb }}

Converts a hex color to its RGBA representation, with an optional alpha channel value (0 to 1). It takes a hex color and an optional alpha value, returning a string like rgba(255, 255, 255, 1).

{{ '#57349B' | hex_to_rgba: 0.5 }}

Default filters provide fallback values and HTML markup.

Returns a fallback value for a variable if it is nil, empty, or false. It takes a variable and a default value as inputs, returning the default if the variable is not set.

{{ product | image_url | default: 'product-default.png' }}

Formats validation errors for a form field into a human-readable string. It takes a form object and a field name, returning error messages or an empty string if none exist.

{{ form.errors | default_errors }}

Generates HTML pagination links for a paginated collection. It takes a paginate object and returns navigation links with customizable styling.

{{ paginate | default_pagination }}

Next and previous labels

You can specify text labels for Next and Previous links to be generated by this filter.

{{ paginate | default_pagination: next: 'Next', previous: 'Previous' }}

Font filters are used to output and modify font objects that are defined in font theme settings.

Generates a CSS @font-face rule for a font asset, specifying its source and properties. It takes a font file name and optional parameters like font-weight or font-style, returning the complete CSS rule.

{{ settings.header_font | font_face }}

You may specify the font display property of the @font-face declaration.

{{ settings.header_font | font_face: font_display: 'swap' }}

Adjusts a font’s properties (e.g., weight, style) for use in a theme. It takes a font object or name and a property to modify, returning the updated font definition.

{% assign bold_font = settings.body_font | font_modify: 'weight', 'bold' %}

h1 { font-weight: {{ bold_font.weight }}; }

Font properties

The font_url filter generates a URL for a font theme setting.

{{ settings.header_font | font_url }}

Filters used to format dates and data into human or machine readable formats.

Formats a date or timestamp into a specified string format. It takes a date input (e.g., string, variable) and a format string, returning the formatted date based on Liquid’s date formatting syntax.

{{ blog.date_created | date: '%B %d, %Y' }}

Current date

You may specify the string 'now' or 'today' to render the current date.

{{ 'now' | date: '%B %d, %Y' }}

Date formatting

The format argument primarily conforms to Ruby's Format for Dates and Times. See to the LiquidJS documentation for details regarding the differences.

You may specify locale-aware formats using the following identifiers.

{{ blog.date_created | date: format: 'on_date' }}

Converts a Liquid object (e.g., array, hash, or variable) into a JSON string. It takes the object as input and returns a compact JSON representation suitable for scripts or APIs.

{{ product | json }}

Converts a Liquid object into a JSON string with formatted, human-readable indentation. It takes the object as input and returns the formatted JSON string.

{{ product | json_pretty }}

Generates structured data markup (e.g., JSON-LD) for SEO purposes, based on an object like a product or blog. It takes the object and optional parameters to customize the schema output.

Product objects are rendered as a schema.org Product or ProductGroup.

Blog objects are rendered as a schema.org Article.

<script type="application/ld+json">
  {{ product | structured_data }}
</script>

HTML filters help render assets and properties using standard HTML elements and attributes.

Retrieves the content of an asset file (e.g., CSS, JS, or text) and outputs it directly in the template. It takes the asset file name as input and returns the file’s raw content.

{{ 'logo.svg' | inline_asset_content }}

Generates an HTML <svg> tag for a placeholder image, typically used for lazy-loaded images. It takes a placeholder type (e.g., product, category) and optional attributes like class or width.

{{ 'product-1' | placeholder_svg_tag }}

The following placeholder names are used for compatibility with Shopify.

Generates an HTML <script> tag for a JavaScript file from the theme’s assets. It takes the asset file name and optional attributes like defer or async, returning the complete tag.

{{ 'main.js' | asset_url | script_tag }}

Generates an HTML <link> tag for a CSS file from the theme’s assets. It takes the asset file name and optional attributes like media, returning the complete tag.

{{ 'main.css' | asset_url | stylesheet_tag }}

Generates an HTML <time> tag with a formatted date or timestamp. It takes a date input and optional format string, returning the tag with a datetime attribute and formatted content.

This filter accepts the same formatting objects as the date filter.

{{ blog.date_created | time_tag }}

Used to translate text and format object output according to a customer's preferred locale or currency.

Formats an address object into a standardized, multi-line string. It takes an address object as input and returns a properly formatted address with fields like street, city, and country.

{{ account.shipping | format_address }}

Retrieves the translated text for a given key from the theme's translation files. It takes a translation key and optional locale or parameters, returning the localized string.

{{ 'path.to.key' | t }}

Math filters are used to perform mathematical operations on numbers.

Returns the absolute value of a number. It takes a number as input and returns its non-negative value, removing any negative sign.

{{ -10 | abs }} # returns 10

Ensures a number is not less than a specified minimum value. It takes a number and a minimum value, returning the greater of the two.

{{ 2 | at_least: 4 }} # returns 4

{{ 6 | at_least: 4 }} # returns 6

Ensures a number is not greater than a specified maximum value. It takes a number and a maximum value, returning the lesser of the two.

{{ 5 | at_most: 4 }} # returns 4

{{ 2 | at_most: 4 }} # returns 2

Rounds a number up to the nearest integer. It takes a number as input and returns the smallest integer greater than or equal to it.

{{ 2.3 | ceil }} # returns 3

Divides a number by another number. It takes a number and a divisor, returning the quotient as a float or integer depending on inputs.

{{ 10 | divided_by: 2 }} # returns 5

{{ 10 | divided_by: 1.2 }} # returns 8.3333333333

Rounds a number down to the nearest integer. It takes a number as input and returns the largest integer less than or equal to it.

{{ 2.3 | floor }} # returns 2

Subtracts one number from another. It takes a number and a value to subtract, returning the difference.

{{ 10 | minus: 2 }} # returns 8

Returns the remainder of a number divided by another. It takes a number and a divisor, returning the remainder of the division.

{{ 5 | modulo: 2 }} # returns 1

Adds one number to another. It takes a number and a value to add, returning the sum.

{{ 1 | plus: 1 }} # returns 2

Rounds a number to a specified number of decimal places. It takes a number and an optional precision value (default: 0), returning the rounded number.

{{ 1.6 | round }} # returns 2

{{ 2.1 | round }} # returns 2

Rounding decimal places

You may specify a number of decimals to round to. If omitted, the filter rounds to the nearest integer.

{{ 1.234 | round: 2 }} # returns 1.23

Multiplies a number by another number. It takes a number and a multiplier, returning the product.

{{ 3 | times: 3 }} # returns 9

Filters that are used to render currency values in different ways.

Formats a number as a currency string using the store’s default currency and settings. Takes a number as input and returns a formatted string, e.g., $12.99.

{{ product.price | money }}

Formats a number as a currency string, including the currency code or symbol. Takes a number and optional currency code, returning a string like $12.99 USD.

{{ product.price | money_with_currency }}

Formats a number as a currency string without the currency code or symbol. Takes a number and returns a string like 12.99.

{{ product.price | money_without_currency }}

Formats a number as a currency string, removing trailing zeros after the decimal point. Takes a number and returns a string like $12 for whole amounts or $12.5 for non-zero decimals.

{{ product.price | money_without_trailing_zeros }}

Filters used to modify strings.

Concatenates a string with another string. Takes a string as input and returns the combined result.

{{ request.origin | append: '/products' }}

Capitalizes the first character of a string and converts the rest to lowercase. Takes a string and returns the capitalized version.

{{ 'this is a capitalized sentence.' | capitalize }}

Converts a string to lowercase. Takes a string and returns the lowercase result.

{{ product.name | downcase }}

Escapes HTML special characters in a string (e.g., < to &lt;). Takes a string and returns the escaped version.

{{ '<p>This will be escaped.</p>' | escape }}

Escapes HTML special characters in a string but does not double-escape already escaped characters. Takes a string and returns the escaped version.

{{ "<p>This is already escaped.</p>" | escape }}

Converts a string to a hyphenated lowercase handle, often used in URLs.

{{ product.name | handleize }} # My Product => my-product

Removes leading whitespace from a string. Takes a string and returns it with no whitespace at the start.

{{ "    Space on the left will be stripped." | lstrip }}

Replaces newline characters (\n) with HTML <br> tags. Takes a string and returns it with newlines converted.

{{ product.description | newline_to_br }}

Prefixes a string with another string. Takes a string as input and returns the combined result.

{{ '/products' | prepend: request.origin }}

Removes all occurrences of a substring from a string. Takes a string and substring, returning the string with all matches removed.

{{ 'one two three' | remove: 'three' }}

Removes the first occurrence of a substring from a string. Takes a string and substring, returning the string with the first match removed.

{{ 'There is a very nice piece in a very beautiful place.' | remove_first: 'very' }}

Removes the last occurrence of a substring from a string. Takes a string and substring, returning the string with the last match removed.

{{ 'There is a very nice piece in a very beautiful place.' | remove_last: 'very' }}

Replaces all occurrences of a substring with another string. Takes a string, the substring to replace, and the replacement string, returning the modified string.

{{ product.slug | replace: '-', ' ' }}

Replaces the first occurrence of a substring with another string. Takes a string, the substring to replace, and the replacement string, returning the modified string.

{{ product.slug | replace_first: '-', ' ' }}

Replaces the last occurrence of a substring with another string. Takes a string, the substring to replace, and the replacement string, returning the modified string.

{{ product.slug | replace_last: '-', ' ' }}

Removes trailing whitespace from a string. Takes a string and returns it with no whitespace at the end.

{{ "Space on the right will be stripped.    " | rstrip }}

Extracts a substring from a string based on index and optional length. Takes a string, start index, and optional length, returning the extracted portion.

{{ '/products' | slice: 1 }} # 'products'

{{ '/products' | slice: 0, 1 }} # '/'

Divides a string into an array based on a delimiter. Takes a string and delimiter, returning an array of substrings.

{{ 'one two three' | split: ' ' }}

Removes leading and trailing whitespace from a string. Takes a string and returns it with whitespace removed from both ends.

{{ "    Space on both sides will be stripped.    " | strip }}

Removes HTML tags from a string, leaving only the text content. Takes a string and returns it without HTML tags.

{{ product.description | strip_html }}

Removes all newline characters (\n) from a string. Takes a string and returns it with newlines removed.

{{ product.description | strip_newlines }}

Shortens a string to a specified length, appending an ellipsis (...) if truncated. Takes a string, length, and optional ellipsis string, returning the truncated result.

{{ product.description | truncate: 40 }}

A second parameter can be used to specify a custom ellipsis, or an empty string for no ellipsis.

{{ product.description | truncate: 40, '))' }}

{{ product.description | truncate: 40, '' }}

Shortens a string to a specified number of words, appending an ellipsis (...) if truncated. Takes a string, word count, and optional ellipsis string, returning the truncated result. Note: HTML tags are treated as words.

{{ product.description | strip_html | truncatewords: 40 }}

A second parameter can be used to specify a custom ellipsis, or an empty string for no ellipsis.

{{ product.description | strip_html | truncatewords: 40, '))' }}

{{ product.description | strip_html | truncatewords: 40, '' }}

Converts a string to uppercase. Takes a string and returns the uppercase result.

{{ product.name | upcase }}

Decodes a URL-encoded string, converting percent-encoded characters back to their original form. Takes a string and returns the decoded version.

{{ 'user%40example.com' | url_decode }} # user@example.com

Encodes a string for safe use in URLs, converting special characters to percent-encoded format. Takes a string and returns the encoded version.

{{ 'user@example.com' | url_decode }} # user%40example.com

Escapes a string for use in URLs, similar to url_encode, ensuring special characters are properly encoded. Takes a string and returns the escaped version.

{{ '<p>This will become URL safe.</p>' | url_escape }}

Filters implemented strictly to enable compatibility with Shopify themes.

Generates a URL for a globally accessible Shopify asset.

{{ 'option_selection.js' | shopify_asset_url }}

Objects represent Swell data that are used to render output in theme templates. This reference describes Liquid objects that are accessible in storefront apps using Swell Liquid for themes, however individual storefront apps like Proxima may differ in how objects or named, or on which pages that are accessible. Refer to documentation on your chosen storefront app for those details.

Model and fields references

The Liquid objects in this guide refer to models and fields that coincide directly with Swell's Backend API. To find descriptions of various object properties listed here, see to the equivalent field in our backend API documentation.

Shopify compatibility

For Shopify themes, this guide will refer to both the Swell object structure and its Shopify equivalent object name, if applicable. Note that when a theme is rendered in Shopify compatibility mode, both Swell object properties, as described here, and Shopify object properties are available at the same time.

Represents the logged-in customer account.

Model: account

Shopify equivalent: customer

Properties

Returned by

Represents a customer’s shipping or billing address.

Model: account address

Shopify equivalent: address

Properties

Returned by

Represents a customer's default billing details.

Model: account.billing

Properties

Returned by

Represents a customer's credit card on file.

Model: account.cards

Properties

Returned by

Generates HTML <option> tags for all available countries in a dropdown. Output should be wrapped in a <select> tag.

Shopify equivalent: all_country_option_tags

<select name="country">
  {{ all_country_option_tags }}
</select>

Represents the user which authored a blog.

Properties

Returned by

Represents a customizable section block in a theme, such as a text or image block.

Shopify equivalent: block

Properties

Returned by

Represents a blog post.

Shopify equivalent: article

Properties

Returned by

Represents a blog category.

Shopify equivalent: blog

Properties

Returned by

Returns the canonical URL for the current page, used to avoid duplicate content pages from being indexed by search engines.

Learn more about canonical URLs here.

Represents the customer’s shopping cart.

Model: cart

Shopify equivalent: cart

Properties

Returned by

Represents a customer's billing address applied to the shopping cart.

Model: cart.billing

Properties

Returned by

Represents a bundle item as a part of a cart item in the customer's shopping cart.

Model: cart.items.bundle_items

Properties

Returned by

Represents a customer's billing address applied to the shopping cart.

Model: cart.discounts

Properties

Returned by

Represents one or more gift cards used as payment sources on the customer's shopping cart.

Model: cart.giftcards

Properties

Returned by

Represents line item within the customer’s shopping cart.

Model: cart.items

Properties

Returned by

Represents an option applied to a line item in the customer's shopping cart. Variants are resolved using these values if a variant_id is not assigned directly.

Model: cart.items.options

Properties

Returned by

Gift card item options

If the item is a gift card, the application may indicate special options to affect the gift card recipient and an optional note.

Option to send to a specific recipient email

Option to send to a gift note

Represents a single tax line applied to an item in the customer's shopping cart.

Model: cart.items.taxes

Properties

Returned by

Represents a chosen purchase option for an item within the customer's shopping cart, either a standard purchase or subscription.

Model: cart.items.purchase_option

Shopify equivalent: selling_plan

Properties

Returned by

Properties

Returned by

Represents a tax line applied to the customer's shopping cart.

Model: cart.taxes

Properties

Returned by

Represents a product category.

Model: category

Shopify equivalent: collection

Properties

Represents a color setting value. Returns a hexidecimal color code when rendered directly.

Shopify equivalent: color

Returned by

{{ settings.color_primary }}

Represents a color scheme setting value. Returns the scheme ID when rendered directly.

Shopify equivalent: color_scheme

Returned by

{{ settings.color_accent_scheme }}

Represents a color scheme group setting value. Used output all color schemes to CSS rules.

Shopify equivalent: color_scheme_group

Returned by

{% for scheme in settings.color_schemes %}
  .color-scheme-{{ scheme.id }} {
    --color-text: {{ scheme.settings.text }};
    --color-background: {{ scheme.settings.background }};
  }
{% endfor %}

Injects necessary scripts and meta tags into the HTML <head> of a page. Automatically populated by the platform for essential functionality.

Returned by

<html>
  <head>
    {{ content_for_header }}
  </head>
  ...
</html>

Renders the main content of a template, excluding the layout file’s wrapper. Used within layout files to insert page-specific content.

Returned by

<html>
  ...
  <body>
    {{ content_for_layout }}
  </body>
  ...
</html>

Represents a content model defined in the store either manually, or as installed by a Swell App.

Model: content

Shopify equivalent: metaobject

Properties

Represents content field values present on another object. For example, product.content contains values in accordance with custom or app-defined fields applied to the product model.

Returned by

{{ product.content.my_content_field }}