Liquid filters

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


add_tag
add_tags
remove_tag
remove_tags

First things first: we don't recommend using Shopify's REST API for tagging. Because this API requires you to specify the entire set of tags all at once, it's very easy to accidentally overwrite the work of another user or system. Instead, we strongly recommend using GraphQL.

Read more: How do I add or remove tags for Shopify resources?

If you must use REST, you can use these filters to make your life a little easier, and manipulate tag strings and arrays more naturally. (All four of these tag filters are case-sensitive.)

{{ "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. If this argument is not provided, the store's local timezone will be used instead.

{{ "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"}}) { ... } }

img_url

This filter mirrors the functionality of Shopify's own img_url filter, and can be used with product, variant, product image, and line item objects. There is one operational difference: if no image is available, this filter will return nil. It will not return a default URL, showing a "no image" image.

Use this filter when building emails (or PDFs, etc) that need to reference specific Shopify images.

{{ product | img_url: "300x300", crop: "center" | default: "https://example.com/no-image.jpg" }}
"https://cdn.shopify.com/s/files/1/2345/6789/1234/products/cog_300x300_crop_center.png?v=1583810430"

in_groups

This filter is an implementation of Array#in_groups. It accepts an array, and an integer count, and – optionally – a "fill_with" option.

{{ "1,2,3" | split: "," | in_groups: 2 | json }}
=> [["1","2"],["3",null]]
{{ "1,2,3" | split: "," | in_groups: 2, fill_with: false | json }}
=> [["1","2"],["3"]]

in_groups_of

This filter is an implementation of Array#in_groups_of. It accepts an array, and an integer count, and – optionally – a "fill_with" option.

This filter is particularly useful when performing work in batches, by making it easy to split an array of potentially large size into smaller pieces of controlled size.

{{ "1,2,3,4,5" | split: "," | in_groups_of: 2 | json }}
=> [["1","2"],["3","4"],["5",null]]
{{ "1,2,3,4,5" | split: "," | in_groups_of: 2, fill_with: false | json }}
[["1","2"],["3","4"],["5"]]

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"=>"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

parse_jsonl

Use this filter to parse a series of JSON objects, each on a separate line, into an array of objects. Useful when preparing stub data for bulk operations.

{% capture jsonl_string %}
  {"id":"gid://shopify/Customer/12345","email":"foo@bar.baz"}
  {"id":"gid://shopify/Customer/67890","email":"bar@baz.qux"}
{% endcapture %}

{% assign json_objects = jsonl_string | parse_jsonl %}

{{ json_objects | map: "email" | join: ", " }}
foo@bar.baz, bar@baz.qux

parse_xml

Use this filter to parse an XML string. (Under the hood, this filter calls Hash::from_xml.) Useful for processing output from third-party APIs, either by responding to "http" actions, or by parsing content from inbound webhooks.

{% capture xml_string %}
<foo>
  <bar>baz</bar>
  <bar>
    <qux>quux</qux>
  </bar>
</foo>
{% endcapture %}

{% assign xml = xml_string | parse_xml %}

{{ xml | json }}
{"foo":{"bar":["baz",{"qux":"quux"}]}}

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.