Skip to content
Log in

Liquid filters reference

On this page

Liquid filters transform the output of variables and expressions using the pipe | syntax: {{ value | filter_name: argument }}. StoreConnect includes all standard Liquid filters plus an extensive set of custom extensions.

For the categorized index of available filters, see Liquid filters.


Math filters

abs

Returns the absolute value.

```liquid

{{ -17 | abs }} {{- “Output: 17” -}}

{{ “-19.86” | abs }} {{- “Output: 19.86” -}} ```

at_least

Returns the larger of the input and the minimum value.

```liquid

{{ 4 | at_least: 5 }} {{- “Output: 5” -}} ```

at_most

Returns the smaller of the input and the maximum value.

```liquid

{{ 4 | at_most: 3 }} {{- “Output: 3” -}} ```

ceil

Rounds up to the nearest whole number.

```liquid

{{ 1.2 | ceil }} {{- “Output: 2” -}}

{{ “3.5” | ceil }} {{- “Output: 4” -}} ```

floor

Rounds down to the nearest whole number.

```liquid

{{ 1.8 | floor }} {{- “Output: 1” -}} ```

round

Rounds to the nearest integer, or to the specified decimal places.

```liquid

{{ 1.2 | round }} {{- “Output: 1” -}}

{{ 183.357 | round: 2 }} {{- “Output: 183.36” -}} ```

plus

Adds a number.

```liquid

{{ 4 | plus: 2 }} {{- “Output: 6” -}} ```

minus

Subtracts a number.

```liquid

{{ 4 | minus: 2 }} {{- “Output: 2” -}} ```

times

Multiplies by a number.

```liquid

{{ 3 | times: 2 }} {{- “Output: 6” -}} ```

divided_by

Divides by a number. Integer division with an integer divisor rounds down — use a float divisor for decimal results.

```liquid

{{ 5 | divided_by: 3 }} {{- “Output: 1 (integer division)” -}}

{{ 20 | divided_by: 7.0 }} {{- “Output: 2.857…” -}} ```

modulo

Returns the remainder of division.

```liquid

{{ 24 | modulo: 7 }} {{- “Output: 3” -}} ```


String filters

append

Appends a string.

```liquid

{{ “/my/url” | append: “.html” }} {{- “Output: /my/url.html” -}} ```

prepend

Prepends a string.

```liquid

{{ “World” | prepend: “Hello “ }} {{- “Output: Hello World” -}} ```

capitalize

Makes the first character uppercase and the rest lowercase.

```liquid

{{ “my GREAT title” | capitalize }} {{- “Output: My great title” -}} ```

downcase / upcase

Converts to lowercase or uppercase.

```liquid

{{ “Han Solo” | downcase }} {{- “Output: han solo” -}}

{{ “title” | upcase }} {{- “Output: TITLE” -}} ```

strip / lstrip / rstrip

Removes whitespace from both sides, the left side only, or the right side only.

```liquid

{{ “ hello “ | strip }} {{- “Output: hello” -}} ```

strip_html

Removes all HTML tags.

```liquid

{{ “The fox jumps” | strip_html }} {{- “Output: The fox jumps” -}} ```

strip_newlines

Removes all newline characters.

escape / escape_once

HTML-escapes special characters. escape_once avoids double-escaping already-escaped entities.

```liquid

{{ “O’Brien & Co.” | escape }} {{- “Output: O'Brien & Co.” -}} ```

url_encode / url_decode

Encodes/decodes URL-unsafe characters.

```liquid

{{ “john@example.com” | url_encode }} {{- “Output: john%40example.com” -}} ```

newline_to_br

Inserts <br /> before each newline.

replace / replace_first

Replaces all occurrences, or only the first occurrence.

```liquid

{{ “do do do” | replace: “do”, “re” }} {{- “Output: re re re” -}}

{{ “do do do” | replace_first: “do”, “re” }} {{- “Output: re do do” -}} ```

remove / remove_first

Removes all occurrences, or only the first.

```liquid

{{ “rain in Spain” | remove: “ain” }} {{- “Output: r in Sp” -}} ```

split

Splits a string into an array.

```liquid

{% assign tags = “red,green,blue” | split: “,” %} {{ tags | join: “ / “ }} {{- “Output: red / green / blue” -}} ```

truncate

Shortens to the specified character count (including the suffix). Default suffix is ....

```liquid

{{ “Mary had a little lamb.” | truncate: 15 }} {{- “Output: Mary had a l…” -}}

{{ “Mary had a little lamb.” | truncate: 15, “–” }} {{- “Output: Mary had a li–” -}}

{{ “Mary had a little lamb.” | truncate: 15, “” }} {{- “Output: Mary had a litt” -}} ```

truncatewords

Shortens to the specified number of words.

```liquid

{{ “Mary had a little lamb.” | truncatewords: 3 }} {{- “Output: Mary had a…” -}} ```

slice

Returns a substring (for strings) or subarray (for arrays) starting at the given index. Negative indices count from the end.

```liquid

{{ “Earthquake” | slice: 2, 5 }} {{- “Output: rthqu” -}} ```

size

Returns the character count of a string or item count of an array.

```liquid

{{ “hello” | size }} {{- “Output: 5” -}} ```


Array/list filters

join

Combines array items into a string.

```liquid

{% assign tags = “red,green,blue” | split: “,” %} {{ tags | join: “ | “ }} {{- “Output: red | green | blue” -}} ```

first / last

Returns the first or last item.

```liquid

{{ “earth,water,fire” | split: “,” | first }} {{- “Output: earth” -}} ```

concat

Concatenates two arrays.

```liquid

{% assign all = fruits | concat: vegetables %} ```

map

Extracts a property from each item.

```liquid

{% assign names = products | map: “name” %} {{ names | join: “, “ }} ```

where

Filters to items with a matching property value. Without a value argument, filters to truthy values.

```liquid

{% assign sale_items = products | where: “on_sale”, true %} {% assign published = articles | where: “published” %} ```

sort / sort_natural

Sorts in case-sensitive or case-insensitive order. Optionally sort by a property.

```liquid

{{ tags | sort | join: “, “ }} {% assign sorted = products | sort: “name” %} ```

reverse

Reverses the order of an array.

```liquid

{{ “earth,water,fire” | split: “,” | reverse | join: “, “ }} {{- “Output: fire, water, earth” -}} ```

uniq

Removes duplicate items.

```liquid

{{ “a,b,a,c” | split: “,” | uniq | join: “, “ }} {{- “Output: a, b, c” -}} ```

compact

Removes nil/null values.

```liquid

{% assign clean = items | compact %} ```

sum

Sums numeric items, or sums a property across objects.

```liquid

{% assign total = cart.items | sum: “quantity” %} ```

push / unshift

Adds an item to the end or beginning of an array.

```liquid

{{ my_list | push: “new_item” | join: “, “ }} {{ my_list | unshift: “first_item” | join: “, “ }} ```

pop / shift

Removes and returns the last or first item (modifies the array).

```liquid

Removed: {{ my_list | pop }} ```

insert

Inserts an item at a specific index. Supports negative indices.

```liquid

{{ my_list | insert: “new”, 2 | join: “, “ }} ```

intersection / union / difference

Set operations on two arrays.

```liquid

{{ list1 | intersection: list2 | join: “, “ }} {{ list1 | union: list2 | join: “, “ }} {{ list1 | difference: list2 | join: “, “ }} ```

match

Filters list items (or characters from a string) matching a regular expression. Includes capture groups for string input. Write the pattern without surrounding slashes. List items that are not text are skipped, and a pattern that runs longer than 0.1 seconds returns an empty list with a warning in the web console.

```liquid

{% assign fruits = “apple,banana,cherry” | split: “,” %} {{ fruits | match: “a” | join: “, “ }} {{- “Output: apple, banana” -}} ```

contains (filter)

Returns true if the array contains the specified item.

```liquid

{{ my_list | contains: “target” }} ```

only / except

Filter array items by property value. only keeps matching items; except removes them. Both support multiple values and chaining.

```liquid

{{ products | only: “type”, “clothing” | pluck: “name” | join: “, “ }} {{ products | except: “type”, “clothing” | pluck: “name” | join: “, “ }} ```


Collection filters

StoreConnect-specific collection operations.

group_by

Groups an array of objects by a property. Returns an array of group objects with name, items, and size.

```liquid

{% assign groups = products | group_by: “category_name” %} {% for group in groups %}

{{ group.name }} ({{ group.size }})

{% for item in group.items %} <p>{{ item.name }}</p> {% endfor %} {% endfor %} ```

pluck

Extracts one or more properties from each item.

```liquid

{{ products | pluck: “name” | json }} {{ products | pluck: “name”, “price” | json }} ```

sample

Returns a random sample of the specified size.

```liquid

{{ products | sample: 3 | pluck: “name” | join: “, “ }} ```

try

Safely accesses a property, returning an empty string if the property doesn’t exist.

```liquid

{{ error_obj | try: “code” }} ```

paginate (filter)

Returns the first page of a collection with the given page size.

```liquid

{{ items | paginate: 5 | join: “,” }} ```

depaginate

Removes pagination limits, fetching all items. Use carefully with large datasets.

```liquid

{% assign all_items = large_collection | depaginate %} ```

json / serialize

Converts any object to a JSON string. Both names are identical.

```liquid

{{ product | json }} {{ cart.items | serialize }} ```


Map/object filters

keys

Returns an array of a map’s keys.

```liquid

{{ my_map | keys | join: “, “ }} ```

merge

Merges two maps. Keys from the second map override matching keys in the first.

```liquid

{{ defaults | merge: overrides | json }} ```

set_key

Adds or updates a key-value pair on a map.

```liquid

{%- new Map data -%} {%- assign data = data | set_key: “name”, “Widget” | set_key: “price”, 9.99 -%} ```

unset_key

Removes one or more keys from a map.

```liquid

{{ config | unset_key: “debug” | json }} {{ config | unset_key: “debug”, “verbose” | json }} ```

collect_keys

Extracts specific keys from each map in an array.

```liquid

{{ users | collect_keys: “name”, “email” | json }} ```

rename_keys

Renames keys (accepts pairs of old_key, new_key). Works on a single map or an array of maps.

```liquid

{{ record | rename_keys: “FirstName”, “first_name”, “LastName”, “last_name” | json }} ```


Date/time filters

datetime

Converts a date/time string to an ISO 8601 timestamp with optional timezone conversion.

```liquid

{{ “2021-02-01 09:00” | datetime }} {{- “Output: 2021-02-01T09:00:00Z” -}}

{{ “2021-06-01T09:00:00+10:00” | datetime, timezone: “Pacific/Auckland” }} {{- “Output: 2021-06-01T11:00:00+12:00” -}} ```

now

Returns the current date and time for the given timezone.

```liquid

{{ “Australia/Sydney” | now }} {{- “Output: current ISO8601 timestamp in AEST” -}} ```

today

Returns the current date for the given timezone.

```liquid

{{ “UTC” | today }} {{- “Output: current date in UTC” -}} ```

time_ago

Returns a human-readable relative time string.

```liquid

{{ article.publish_on | time_ago }} {{- “Output: about 3 days ago” -}} ```

time_duration

Returns a human-readable duration from a number of seconds.

```liquid

{{ 3600 | time_duration }} {{- “Output: about 1 hour” -}} ```

date (enhanced)

Formats a date using strftime syntax, with timezone support. Accepts date strings, "now", "today", or Unix timestamps.

```liquid

{{ “2021-07-01T09:00:00Z” | date: “%a, %b %-d, %Y” }} {{- “Output: Thu, Jul 1, 2021” -}}

{{ “now” | date: “%Y-%m-%d”, timezone: “Australia/Sydney” }} {{- “Output: current date in Sydney” -}} ```

Common format tokens:

Token Description Example
%Y Year 2024
%m Month (01–12) 07
%-m Month without padding 7
%d Day (01–31) 01
%-d Day without padding 1
%H Hour 24h 14
%M Minute 30
%a Abbreviated day Thu
%A Full day name Thursday
%b Abbreviated month Jul
%B Full month name July

date_add

Adds a duration to a date. Accepts negative values for subtraction. Options: years, months, weeks, days, hours, minutes, seconds, timezone.

```liquid

{{ “2021-03-01T09:00:00” | date_add: days: 5 }} {{- “Output: 2021-03-06T09:00:00Z” -}}

{{ “2021-03-01T09:00:00” | date_add: days: -5 }} {{- “Output: 2021-02-24T09:00:00Z” -}} ```


Number formatting filters

money

Formats a number as currency. Strips .00 cents by default.

```liquid

{{ 12.76 | money }} {{- “Output: $12.76” -}}

{{ 12.00 | money }} {{- “Output: $12” -}}

{{ 12.95 | money, unit: ‘€’ }} {{- “Output: €12.95” -}}

{{ 12.70 | money, compact: true }} {{- “Output: $12.7” -}}

{{ 12.70 | money, compact: false }} {{- “Output: $12.70” -}} ```

points

Formats a number as loyalty points with comma separators and a “pts” suffix.

```liquid

{{ 1200 | points }} {{- “Output: 1,200 pts” -}} ```

number

Formats a number with locale-aware options.

```liquid

{{ 12000 | number, delimiter: “,” }} {{- “Output: 12,000” -}}

{{ 12.76 | number, separator: “,” }} {{- “Output: 12,76” -}}

{{ 12 | number, precision: 3 }} {{- “Output: 12.000” -}}

{{ 99.00 | number, compact: true }} {{- “Output: 99” -}} ```

Options: compact, delimiter, separator, precision


Text filters

j

JavaScript-escapes a string for safe use in JS string literals.

```liquid

```

unescape

Unescapes HTML-escaped characters.

```liquid

{{ “<p>Hello</p>” | unescape }} {{- “Output: <p>Hello</p>” -}} ```

parameterize

Converts a string to a URL-friendly slug (lowercase, hyphens, no special characters).

```liquid

{{ “On Sale” | parameterize }} {{- “Output: on-sale” -}} ```

hmac

Generates an HMAC signature for a string using a secret key.

```liquid

{{ “data” | hmac: “secret” }} {{ “data” | hmac: “secret”, algorithm: “SHA256” }} {{ “data” | hmac: “secret”, digest: “Base64” }} ```

Algorithms: SHA (default), SHA1, SHA224, SHA256, SHA384, SHA512, MD5, RIPEMD160

Digests: Hex (default), Base64

markdown

Converts Markdown to sanitized HTML using GitHub-Flavored Markdown.

```liquid

{{ article.body | markdown }} {{ “bold and italic” | markdown }} ```

encrypt / decrypt

Encrypts data into a token, or decrypts a token back to the original value. Accepts an optional salt for key derivation.

```liquid

{% assign token = sensitive_value | encrypt, salt: “my-salt” %} {% assign original = token | decrypt, salt: “my-salt” %} ```

deserialize

Parses a JSON or XML string into a Liquid map or list. A string that starts with < is read as XML, and anything else as JSON. Invalid input, or input over 1 MB, returns nothing. POS templates parse JSON only. See the deserialize filter for more examples.

```liquid

{% assign data = ‘{“title”:”Hello”,”count”:42}’ | deserialize %} {{ data.title }}: {{ data.count }}

{% assign book = ‘Ruby’ | deserialize %} {{ book.book.title }} {{- “Output: Ruby” -}} ```


URL filters

params

Adds query parameters to a URL path. Handles existing query strings correctly.

```liquid

{{ “/products” | params: page: 2, sort: “name” }} {{- “Output: /products?page=2&sort=name” -}}

{{ “/products?category=shoes” | params: page: 2 }} {{- “Output: /products?category=shoes&page=2” -}} ```


Video filters

youtube

Returns a responsive HTML embed for a YouTube video ID.

```liquid

{{ product.videos | first | youtube }} {{ “video-id-here” | youtube, start_at: 30 }} ```

vimeo

Returns a responsive HTML embed for a Vimeo video ID.

```liquid

{{ “video-id-here” | vimeo }} {{ “video-id-here” | vimeo, start_at: 60 }} ```


Theme filters

t

Looks up a translation key in the theme’s translation file (translations/en.default.json). Supports variable interpolation.

```liquid

{{ “welcome.title” | t }} {{ “products.count” | t: count: 5 }} ```

If a key is not found, returns: "missing translation: sc.locale.{key} for locale: {locale}"

asset_url

Returns the URL for a theme asset file.

```liquid

Logo {% assign css_url = “styles/theme.css” | asset_url %} ```


Image filters

These filters work on an Image object, such as product.image, and build Cloudinary URLs at the size you ask for. Images are never enlarged past the original, and no dimension exceeds 5120 pixels. Both are available in storefront templates, not POS templates.

image_url

Returns a Cloudinary URL for the image at a custom width, height, crop and quality. Pass one dimension and the other is calculated from the aspect ratio. See the image_url filter for crop modes and quality values.

```liquid

{{ product.image | image_url: width: 400 }} {{ product.image | image_url: width: 1200, height: 600, crop: “fill”, quality: “best” }} ```

image_tag

Returns a complete <img> element with a sized src, an automatic responsive srcset, alt text from the media record, width and height, and loading="lazy" and decoding="async" by default. Takes the same options as image_url, plus alt, class, id, loading, decoding, fetchpriority, sizes, widths, srcset, and data-* and aria-* attributes. See the image_tag filter for how the srcset is built.

```liquid

{{ product.image | image_tag: width: 400, sizes: “(max-width: 640px) 50vw, 25vw”, class: “product-card__image” }} {{ article.hero_image | image_tag: width: 1600, height: 600, crop: “fill”, widths: “800,1200,1600”, sizes: “100vw”, loading: “eager”, fetchpriority: “high” }} ```


Record filters

record_fields

Returns the accessible fields on a record or drop as an array.

```liquid

{{ product | record_fields | join: “, “ }} ```

record_relationships

Returns the accessible relationships on a record or drop.

```liquid

{{ product | record_relationships | join: “, “ }} ```

record_name

Returns the type name of a record or drop.

```liquid

{{ product | record_name }} {{- “Output: Product” -}} ```

cast

Converts values between types. For primitive types, converts strings to numbers/booleans. For records from {% query %}, converts to the corresponding drop type.

```liquid

{{ “123” cast: “integer” }}
{{ “true” cast: “boolean” }}
{{ “3.14” cast: “float” }}

{% query ‘Product2’ as records %} {% for record in records %} {% assign product = record | cast: “Product” %} {{ product.name }} {% endfor %} ```

recordize

Converts a drop back to its underlying record representation.


Product content filters

These filters render product-associated content blocks using built-in templates.

show_traits

Renders all product traits using the built-in template. Falls back to the master product’s trait category for variants that don’t have their own.

```liquid

{{ current_product | show_traits }} ```

render_content_blocks

Renders all content blocks of a specified type for a product.

```liquid

{{ product | render_content_blocks: “downloads” }} ```

Typed content block filters

Each filter renders content blocks of the named type. All accept a product drop.

Filter Alias Description
downloads_content_blocks render_downloads_content_blocks Downloadable files (PDFs, manuals)
features_content_blocks render_features_content_blocks Key features and highlights
specifications_content_blocks render_specifications_content_blocks Technical specifications
support_content_blocks render_support_content_blocks Support and help content
warranty_content_blocks render_warranty_content_blocks Warranty terms

```liquid

{{ product | features_content_blocks }} {{ product | specifications_content_blocks }} ```

Utility filters

default

Sets a default value for any variable which is nil, false, or blank.

```liquid

{% assign hide_price = false %} {{ hide_price | default: true, allow_false: true }} {{- “Output: false” -}} ```

Was this article helpful?

Was this article helpful?