Swell Liquid Reference | Swell Developer Center

Filters are used to modify Liquid output.

Array filters are used to modify arrays.

Removes empty values from an array.

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.

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.

You can also use a custom separator for joined items.

Returns the last element of an array.

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.

Returns the number of items in an array.

Dot notation

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

{% assign count = array.size %}

Sorts elements of an array.

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.

You can also specify a property to sum object values.

{{ array | sum: 'property' }}

Removes duplicate elements from an array.

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.

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.

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