Theme Filters

Introduction

Filters are simple methods that modify the output of numbers, strings, variables and objects. They are placed within an output tag {{ }} and are separated with a pipe character |.

Input

<!-- product.title = "Awesome Shoes" -->

{{ product.title | upcase }}

Output

AWESOME SHOES

Money Filters

money

Returns money like NZ$10.20 or A$1.20 or $99.99 or €5.55. If value is passed to money filter (rather then object property ie "14.99" instead of variant.price) scale can be provided to override default scale value.

Input

<!-- USD 25.90 -->
{{ product.master_variant.price|money }}
<!-- AUD 25.90 -->
{{ product.master_variant.price|money }}
<!-- NZD 25.90 -->
{{ "2595000"|money }}
<!-- EUR 25.90 -->
{{ "2595000"|money: 100000 }}
<!-- RUR 25.90 -->
{{ "2595"|money: 100 }}

Output

$25.90
A$25.90
NZ$25.90
€25.90
RUR25.90

money_without_currency

Returns money like 10.20

Input

<!-- EUR 25.90 -->
{{ "2595000"|money }}

Output

25.90

String Filters

append

Appends characters to a string.

Input

{{ 'sales' | append: '.jpg' }}

Output

sales.jpg

camelcase

Converts a string into CamelCase.

Input

{{ 'coming-soon' | camelcase }}

Output

ComingSoon

capitalize

Capitalizes the first word in a string

Input

{{ 'capitalize me' | capitalize }}

Output

Capitalize me

title

Returns a titlecased version of the value. Words will start with uppercase letters, all remaining characters are lowercase

Input

{{ 'title me' | title }}

Output

Title Me

downcase / lower

Converts a string into lowercase.

Input

{{ 'I WANT THIS TO BE LOWER CASE' | downcase }}

Output

i want this to be lower case

escape

Escapes a string.

Input

{{ "<p>test</p>" | escape }}

Output

<!-- The <p> tags are not rendered, actual output is -->
&lt;p&gt;test&lt;/p&gt;

raw

Marks the value as being "safe", which means this variable will not be escaped if raw is the last filter applied to it

Input

{{ "<p>test</p>" | strip | raw }}
{{ "<p>test</p>" | strip }}

Output

<!-- The <p> tags are rendered, actual output is -->
<p>test</p>
 <!-- The <p> tags are not rendered, actual output is -->
&lt;p&gt;test&lt;/p&gt;

handle / handleize

Formats a string into a handle.

Input

{{ '100% M & Ms!!!' | handleize }}

Output

100-m-ms

md5

Converts a string into an MD5 hash. An example use case for this filter is showing the Gravatar image associated with the poster of a blog comment:

Input

<img src="https://www.gravatar.com/avatar/{{ comment.email | remove: ' ' | strip_newlines | downcase | md5 }}" />

Output

 <img src="https://www.gravatar.com/avatar/2a95ab7c950db9693c2ceb767784c201" />

newline_to_br / nl2br

Inserts a
linebreak HTML tag in front of each line break in a string.

Input

{% capture var %}
One
Two
Three
{% endcapture %}
{{ var | newline_to_br }}

Output

One<br />
Two<br />
Three<br />

pluralize

Outputs the singular or plural version of a string based on the value of a number. The first parameter is the singular string and the second parameter is the plural string.

Input

{{ cart.item_count }}
{{ cart.item_count | pluralize: 'item', 'items' }}

Output

3 items

prepend

Prepends characters to a string.

Input

{{ 'sale' | prepend: 'Made a great ' }}

Output

Made a great sale

remove

Removes all occurrences of a substring from a string.

Input

{{ "Hello, world. Goodbye, world." | remove: "world" }}

Output

Hello, . Goodbye, .

remove_first

Removes only the first occurrence of a substring from a string.

Input

{{ "Hello, world. Goodbye, world." | remove_first: "world" }}

Output

Hello, . Goodbye, world.

replace

Replaces all occurrences of a string with a substring.

Input

<!-- product.title = "Awesome Shoes" -->
{{ product.title | replace: 'Awesome', 'Mega' }}

Output

Mega Shoes

replace_first

Replaces the first occurrence of a string with a substring.

Input

<!-- product.title = "Awesome Awesome Shoes" -->
{{ product.title | replace_first: 'Awesome', 'Mega' }}

Output

Mega Awesome Shoes

slice

The slice filter returns a substring, starting at the specified index. An optional second parameter can be passed to specify the length of the substring. If no second parameter is given, a substring of one character will be returned.

Input

{{ "hello" | slice: 0 }}
{{ "hello" | slice: 1 }}
{{ "hello" | slice: 1, 3 }}

Output

h
e
ell

split

The split filter takes on a substring as a parameter. The substring is used as a delimiter to divide a string into an array. You can output different parts of an array using array filters.

Input

{% assign words = "Hi, how are you today?" | split: ' ' %}
{% for word in words %}
{{ word }}
{% endfor %}

Output

Hi,
how
are
you
today?

strip

Strips tabs, spaces, and newlines (all whitespace) or other characters from the beginning and end of a string

Input

"{{ '   too many spaces      ' | strip }}"
"{{ '   too many dots...' | strip: "." }}"

Output

"too many spaces"
"   too many dots"

lstrip

Strips tabs, spaces, and newlines (all whitespace) or other characters from the beginning of a string

Input

"{{ '   too many spaces           ' | lstrip }}"
"{{ '...too many dots.............' | lstrip: "." }}"

Output

"too many spaces           "
"too many dots............."

rstrip

Strips tabs, spaces, and newlines (all whitespace) or other characters from the end of a string

Input

"{{ '              too many spaces      ' | rstrip }}"
"{{ '..............too many dots........' | rstrip: "." }}"

Output

"              too many spaces"
"..............too many dots"

strip_html

Strips all HTML tags from a string.

Input

{{ "<h1>Hello</h1> World" | strip_html }}

Output

Hello World

strip_newlines

Removes any line breaks/newlines from a string.

Input

{{ product.description | strip_newlines }}

truncate

Truncates a string down to 'x' characters, where x is the number passed as a parameter. An ellipsis (...) is appended to the string and is included in the character count.

Input

{{ "The cat came back the very next day" | truncate: 10 }}

Output

The cat...

truncatewords

Truncates a string down to 'x' words, where x is the number passed as a parameter. An ellipsis (...) is appended to the truncated string.

Input

{{ "The cat came back the very next day" | truncatewords: 4 }}

Output

The cat came back...

uniq

Removes any duplicate instances of an element in an array.

Input

{% assign fruits = "orange apple banana apple orange" %}
{{ fruits | split: ' ' | uniq | join: ' ' }}

Output

orange apple banana

upcase / upper

Converts a string into uppercase.

Input

{{ 'i want this to be uppercase' | upcase }}

Output

I WANT THIS TO BE UPPERCASE

url_escape

Identifies all characters in a string that are not allowed in URLS, and replaces the characters with their escaped variants.

Input

{{ "<hello> & <shopify>" | url_escape }}

Output

%3Chello%3E%20&%20%3Cshopify%3E

url_param_escape

Replaces all characters in a string that are not allowed in URLs with their escaped variants, including the ampersand (&).

Input

{{ "<hello> & <shopify>" | url_param_escape }}

Output

%3Chello%3E%20%26%20%3Cshopify%3E

reverse

Reverses a sequence, a mapping, or a string.

For sequences and mappings, numeric keys are not preserved. To reverse them as well, pass true as an argument to the reverse filter:

Input

{{ "reverse me"|reverse }}
{{ "1<2<3<4"|split:"<"|reverse|join:">"|raw }}

Output

em esrever
4>3>2>1

format

Formats a given string by replacing the placeholders (placeholders follows the sprintf notation)

Input

{{ "I like %s and %s."|format("apples", "oranges") }}

Output

I like apples and oranges.

Math Filters

abs

Returns the absolute value.

Input

{{ -4.6 | abs }}
{{ 6 | abs }}

Output

4.6
6

ceil

Rounds an output up to the nearest integer.

Input

{{ 4.6 | ceil }}
{{ 4.3 | ceil }}

Output

5
5

divided_by

Divides an output by a number. The output is rounded down to the nearest integer.

Input

<!-- product.price = 200 -->
{{ product.price | divided_by: 10 }}

Output

floor

Rounds an output down to the nearest integer.

Input

{{ 4.6 | floor }}
{{ 4.3 | floor }}

Output

4
4

minus

Subtracts a number from an output.

Input

<!-- product.price = 200 -->
{{ product.price | minus: 15 }}

Output

plus

Adds a number to an output.

Input

<!-- product.price = 200 -->
{{ product.price | plus: 15 }}

Output

round

Rounds the output to the nearest integer or specified number of decimals.

Input

{{ 4.6 | round }}
{{ 4.3 | round }}
{{ 4.5612 | round: 2 }}

Output

5
4
4.56

times

Multiplies an output by a number.

Input

<!-- product.price = 200 -->
{{ product.price | times: 1.15 }}

Output

modulo

Divides an output by a number and returns the remainder.

Input

{{ 12 | modulo: 5 }}

Output

HTML Filters

image_tag

Generates an image tag.

Input

{{ 'smirking_gnome.gif' | asset_url | img_tag }}

Output

<img src="https://vend-ecom-prod-assets.s3.amazonaws.com/storefront-assets/4f810410-22ac-43c4-965a-5733bce67816/2c0d4fb8-8e01-11e5-b255-0a6afe88c81b/39baaafe-97bf-11e5-b255-0a6afe88c81b.jpg" alt="" />

script_tag

Generates a script tag.

Input

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

Output

<script src="https://vend-ecom-prod-assets.s3.amazonaws.com/storefront-assets/4f810410-22ac-43c4-965a-5733bce67816/2c0d4fb8-8e01-11e5-b255-0a6afe88c81b/350b7b27-8e01-11e5-b255-0a6afe88c81b.js" type="text/javascript"></script>

stylesheet_tag

Generates a stylesheet tag.

Input

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

Output

<link href="https://vend-ecom-prod-assets.s3.amazonaws.com/storefront-assets/4f810410-22ac-43c4-965a-5733bce67816/2c0d4fb8-8e01-11e5-b255-0a6afe88c81b/2eecc09f-97c0-11e5-b255-0a6afe88c81b.css" rel="stylesheet" type="text/css" media="all" />

Internationalisation Filters

t

The translation filter retrieves the translated content from the locale file for the active language. Passing count to the t filter allows custom pluralisation. Supported pluralization keys are:

zero
one
two
other

Input

{% if customer %}
<h1>{{ 'customer.orders.order_count' | t: count: customer.orders_count }}</h1>
{% endif %}

locales/en.default.json
{
    "customer": {
    "orders": {
        "order_count": {
            "zero": "Looks like you haven't made any orders yet",
            "one": "You've made one order with us",
            "other": "You've made {{ count }} orders with us"
        }
    }
  }
}

Output

// count = 1
<h1>You've made one order with us</h1>

// count = 12
<h1>You've made 12 orders with us</h1>

URL Filters

img_url

Returns the URL of an image. Accepts an image size as a parameter. The img_url filter can be used on the following objects: product

Input

 {{ product | img_url: 'small' }}

Output

 https://s3.amazonaws.com/vend-images/product/ss/2/6/26c907f60c9fe73fb16effd3ffbeada94f767004.png

Parameters: image sizes

tiny:

Returns the image at a maximum size of 40 by 40 pixels.

small:

Returns the image at a maximum size of 50 by 50 pixels.

medium:

Returns the image at a maximum size of 100 by 100 pixels.

large:

Returns the image at a maximum size of 150 by 150 pixels.

thumb:

Returns the image at a maximum size of 160 by 160 pixels.

standard:

Returns the image at a maximum size of 350 by 350 pixels.

original:

Returns the image at a maximum size of 1920 by 1920 pixels.

within

Creates a collection-aware product URL by prepending /collections/collection-handle to a product URL, where collection-handle is the handle of the collection that is currently being viewed.

Input

<a href="{{ product.url | within: collection }}">{{ product.title }}</a>

Output

<a href="/collections/frontpage/products/alien-poster">Alien Poster</a>

asset_url

Returns the URL of a file in the "assets" folder of a theme.

Input

{{ 'shop.css' | asset_url }}

Output

https://vend-ecom-prod-assets.s3.amazonaws.com/storefront-assets/4f810410-22ac-43c4-965a-5733bce67816/2c0d4fb8-8e01-11e5-b255-0a6afe88c81b/34f08c6c-8e01-11e5-b255-0a6afe88c81b.css

link_to

Generates an HTML link.

Input

{{ 'Lightspeed' | link_to: 'https://www.lightspeedhq.com' }}

Output

<a href="https://www.lightspeedhq.com">Lightspeed</a>

Additional Filters

json

Converts a value into JSON format.

Input

{{ ["dog", "cat"]|json|raw }}
{{ product|json|raw }}

Output

["dog","cat"]
{"name":"Product One"}

default

Returns the passed default value if the value is undefined or empty, otherwise the value of the variable

Input

Dear {{ customer.name | default: "customer" }}

Output

<!-- If customer.name is nil -->
Dear customer

<!-- If customer.name is "" -->
Dear customer

<!-- If customer.name is "   " -->
Dear

date

Converts a timestamp into another date format. The format specifier is the same as supported by date. Timezone can be specified via second parameter, by default UTC timezone is used.

Input

{{ "now"|date:"m/d/Y H:i:s" }}
{{ "now"|date:"m/d/Y H:i:s", "Europe/Paris" }}

Output

01/05/2016 03:21:03
01/05/2016 04:21:55

date_modify

Modifies a date with a given modifier string

Input

{{ post.published_at|date:"m/d/Y" }}
{{ post.published_at|date_modify:"+1 day"|date:"m/d/Y" }}

Output

12/31/2015
01/01/2016

number_format

Formats numbers in a same was as number_format function.

Input

{{ 200.35|number_format }}
{{ 9800.333|number_format:"2", '.', ',' }}

Output

9,800
9,800.33

Array Filters

Also see article "Theme Objects \ Array" for dot notation in cases where it needs to be used inside a tag.

batch

The batch filter "batches" items by returning a list of lists with the given number of items. A second parameter can be provided and used to fill in missing items.

Input

{% for row in collection.products|batch:2 %}
  {% for product in row %}
      {{ product.name }}<br />
  {% endfor %}
  <hr />
{% endfor %}

Output

Product 1
Product 2
---------------------
Product 3
Product 4
---------------------

first

Returns the first element of an array.

Input

<!-- product.tags = "sale", "mens", "womens", "awesome" -->
{{ product.tags | first }}

Output

sale

last

Gets the last element passed in an array.

Input

<!-- product.tags = "sale", "mens", "womens", "awesome" -->
{{ product.tags | last }}

Output

awesome

join

Joins the elements of an array with the character passed as the parameter. The result is a single string.

Input

{{ [1, 2, 3]|join }}
{{ product.tags | join: ', ' }}

Output

123
tag1, tag2, tag3

keys

Returns the keys of an array. It is useful when you want to iterate over the keys of an array

Input

{{ "a":1,"b":2,"c":3}|keys|join }}

Output

length / size

Returns the size of a string or an array.

Input

{{ collection.products | size }}
{{ 'is this a 30 character string?' | size }}

Output

5
30

sort

Sorts an array.

Input

{{ ['a','c','A','b']|sort|join }}

Output

Aabc