Liquid filters

Mechanic include all filters available in Liquid's standard library. We also add a few of our own. :)


add_tag
add_tags
remove_tag
remove_tags

Use these filters to manipulate tag strings. All four of these tag filters are case-sensitive.

For background: Instead of working with tags as arrays, the Shopify API works with tags as comma-delimited strings; this makes it complicated to add or remove tags using only standard Liquid. These filters make it very simple.

{{ "a, b" | add_tag: "c" }}
=> a, b, c

{{ "a, b, e" | add_tags: "c", "d" }}
=> a, b, c, d, e

{{ "a, b, e" | add_tags: "c", "d", sort: false }}
=> a, b, e, c, d

{{ "a, b, c" | remove_tag: "b" }}
=> a, b

{{ "a, b, c" | remove_tags: "a", "c" }}
=> b

If supplied an array, these filters will return an array as well:

{{ "a,b,e" | split: "," | add_tags: "c", "d" | join: "-" }}
=> a-b-c-d-e

{{ "a,b,c,d,e" | split: "," | remove_tags: "c", "d" | join: "-" }}
=> a-b-e

base64
decode_base64

Use these filters to convert strings to their base64 representation, and back again.

{{ "hello!" | base64 }}
=> aGVsbG8h

{{ "aGVsbG8h" | decode_base64 }}
=> hello!

{{ "hello!" | base64 | decode_base64 }}
=> hello!

browser

This filter converts a browser user agent string into an object that represents the browser itself.

{% assign browser = "Mozilla/5.0 (iPhone; CPU iPhone OS 12_4 like Mac OS X) AppleWebKit/605.1.15 (KHTML, like Gecko) GSA/79.0.259819395 Mobile/16G77 Safari/604.1" | browser %}

{{ browser }}

name: {{ browser.name }}

version: {{ browser.version }}
major version: {{ browser.version.major }}
minor version: {{ browser.version.minor }}

os: {{ browser.os }}
os name: {{ browser.os.name }}
os version: {{ browser.os.version }}
os major version: {{ browser.os.version.major }}
os minor version: {{ browser.os.version.minor }}

device: {{ browser.device }}
device name: {{ browser.device.name }}
device brand: {{ browser.device.brand }}
device model: {{ browser.device.model }}
Google 79.0.259819395

name: Google

version: 79.0.259819395<br>major version: 79<br>minor version: 0

os: iOS 12.4<br>os name: iOS<br>os version: 12.4<br>os major version: 12<br>os minor version: 4

device: iPhone<br>device name: iPhone<br>device brand: Apple<br>device model: iPhone

For reference, we use data from Browserscope to match user agents.


csv

Use this filter to convert a two-dimensional array to a CSV-formatted string. Useful when composing email attachments.

{% assign rows = array %}

{% assign header = array %}
{% assign header[0] = "Name" %}
{% assign header[1] = "Email" %}

{% assign rows[0] = header %}

{% for customer in shop.customers %}
  {% assign row = array %}
  {% assign row[0] = customer.first_name | append: " " | append: customer.last_name %}
  {% assign row[1] = customer.email %}
  {% assign rows[rows.size] = row %}
{% endfor %}

{{ rows | csv }}
=> "Name,Email\nJane Lopez,jane@example.com"

date

This filter works identically to Shopify's implementation, apart from a single additional argument: providing a tz value will result in the rendered date being returned in the provided timezone, instead of in the store's local timezone.

{{ "now" | date: "%Y-%m-%d %H:%M %z" }}
=> "2019-01-01 09:00 +0900"

{{ "now" | date: "%Y-%m-%d %H:%M %z", tz: "UTC" }}
=> "2019-01-01 00:00 +0000"

Read more: Shopify / Liquid reference / Additional filters


e164

This filter accepts a phone number – country code is required! – and outputs it in standard E.164 format. If the number does not appear valid, the filter returns nil.

{{ "1 (312) 456-7890" | e164 }}
=> "13124567890"

{{ "+43 670 1234567890" | e164 }}
=> "436701234567890"

{{ "000" | e164 | json }}
=> "null"

graphql_arguments

This filter accepts a hash, and outputs it as a formatted set of GraphQL arguments, suitable for use in a query or mutation. This filter will also accept individual values, for use within the composition of a single argument.

{% assign args = hash %}
{% assign args["query"] = "email:foo@bar.baz" %}
{% assign args["first"] = 10 %}
{ customers({{ args | graphql_arguments }}) { ... } }
{ customers(query: "email:foo@bar.baz", first: 10) { ... } }
{% assign input = '{"foo": "bar", "baz": ["qux", 123, null], "quux": {"a": "b", "c": "d"}}' | parse_json %}
{ foo(input: {{ input | graphql_arguments }}) { ... } }
{ foo(input: {foo: "bar", baz: "qux", 123, null], quux: {a: "b", c: "d"}}) { ... } }

match

Use this filter to match a string with a Ruby-compatible regular expression pattern (see Regexp).

This filter returns the entire matched string (i.e. MatchData#to_s). Use the "captures" or "named_captures" lookups to receive an array or hash of captures, respectively (i.e. MatchData#captures, MatchData#named_captures).

{{ "It's a lovely day!" | match: "(?<=a ).*(?= day)" }}
=> "lovely"

{% assign match = "It's a lovely day!" | match: "a (bucolic|lovely) day" %}
{{ match.captures }}
=> ["lovely"]

{% assign match = "It's a lovely day!" | match: "a (?<adjective>bucolic|lovely) day" %}
{{ match.named_captures.adjective }}
=> {"adjective"=>"lovely"}

{% assign match = "It's a lovely day!" | match: "a (?i:LOVELY) day" %}
{{ match }}
=> "a lovely day"

md5
sha256
hmac_sha1
hmac_sha256

These filters work identically to Shopify's implementation.

Read more: Shopify / Liquid reference / String filters


parse_date

Use this filter to parse a date string, when its exact format is known. This filter is useful for strings that contain an ambiguous date value, like "01/01/01".

This filter returns an ISO8601 string, representing the parsed date value in the store's local timezone. If the supplied date string cannot be parsed successfully, the filter will return nil.

The date format you provide is given in the same format as the standard Liquid date filter, which is to say, is the same format as Ruby's strftime, and can be referenced with sites like strfti.me. Under the hood, this filter uses ActiveSupport::TimeZone#strptime, and inherits its behavior with regard to missing upper components.

To reformat a date string, pass the resulting value back into the standard Liquid date filter.

{{ "01-01-20" | parse_date: "%m-%d-%y" }}
=> "2020-01-01T00:00:00+11:00"

{{ "01-01-20" | parse_date: "%m-%d-%y" | date: "%Y-%m-%d" }}
=> "2020-01-01"

{{ "ab-cd-ef" | parse_date: "%m-%d-%y" }}
=> nil

parse_json

Use this filter to transform a JSON string into an object that can be inspected and traversed.

{% capture json_string %}
  {
    "hello": "world"
 }
{% endcapture %}

{% assign json_object = json_string | parse_json %}

hello {{ json_object.hello }}
hello world

sample

This filter can be used on any array. Used without any arguments, it returns a single random element from the array. Provide an integer argument to return another array of that size, containing a random subset of the input array.

{{ "1,2,3" | split: "," | sample }}
=> "2"

{{ "1,2,3" | split: "," | sample: 2 | join: "," }}
=> "3,1"

shopify

This filter accepts a GraphQL query string, sends it to Shopify, and returns the full response – including "data" and "errors".

Tip: Use Shopify's GraphiQL query builder to quickly and precisely assemble your queries.

{% capture query %}
  query {
    shop {
      primaryDomain {
        host
        id
        sslEnabled
        url
      }
      myshopifyDomain
    }
  }
{% endcapture %}

{{ query | shopify | json }}

=> {"data":{"shop":{"primaryDomain":{"host":"example.myshopify.com","id":"gid:\/\/shopify\/Domain\/1234567890","sslEnabled":true,"url":"https:\/\/example.myshopify.com"},"myshopifyDomain":"example.myshopify.com"}},"extensions":{"cost":{"requestedQueryCost":2,"actualQueryCost":2,"throttleStatus":{"maximumAvailable":1000.0,"currentlyAvailable":998,"restoreRate":50.0}}}}

sum

Use this on an array of numbers to quickly generate their sum.

{{ "[1, 2, 3]" | parse_json | sum }}
=> 6

unindent

Use this filter on strings to remove indentation from strings.

{% capture message %}
  Hello, friend!
  It's a mighty fine day!
{% endcapture %}

{{ message | unindent }}
Hello, friend!
It's a mighty fine day!
Did this answer your question? Thanks for the feedback There was a problem submitting your feedback. Please try again later.