Skip to main content

Liquid Filters

O2VEND provides a comprehensive set of Liquid filters for data manipulation, formatting, and transformation. This guide covers all available filters.

Filter Syntax​

Filters are applied using the pipe (|) operator:

{{ value | filter_name }}
{{ value | filter_name: argument }}
{{ value | filter_name: arg1, arg2 }}

String Filters​

Text Transformation​

upcase​

Converts string to uppercase.

{{ "hello" | upcase }}
<!-- Output: HELLO -->

downcase​

Converts string to lowercase.

{{ "HELLO" | downcase }}
<!-- Output: hello -->

capitalize​

Capitalizes first letter of each word.

{{ "hello world" | capitalize }}
<!-- Output: Hello World -->

Text Manipulation​

truncate​

Truncates string to specified length.

{{ "Long text here" | truncate: 10 }}
<!-- Output: Long text... -->

truncatewords​

Truncates to specified number of words.

{{ "This is a long sentence" | truncatewords: 3 }}
<!-- Output: This is a... -->

strip​

Removes leading and trailing whitespace.

{{ "  hello  " | strip }}
<!-- Output: hello -->

lstrip / rstrip​

Removes leading or trailing whitespace.

{{ "  hello  " | lstrip }}
<!-- Output: hello  -->

replace​

Replaces occurrences of a string.

{{ "Hello World" | replace: "World", "O2VEND" }}
<!-- Output: Hello O2VEND -->

remove​

Removes all occurrences of a string.

{{ "Hello World" | remove: "l" }}
<!-- Output: Heo Word -->

prepend / append​

Adds text before or after string.

{{ "world" | prepend: "Hello " }}
<!-- Output: Hello world -->

{{ "Hello" | append: " world" }}
<!-- Output: Hello world -->

split​

Splits string into array.

{% assign words = "one,two,three" | split: "," %}
{% for word in words %}
  {{ word }}
{% endfor %}

join​

Joins array into string.

{% assign words = "one,two,three" | split: "," %}
{{ words | join: " - " }}
<!-- Output: one - two - three -->

URL and HTML​

url_encode / url_decode​

Encodes/decodes URL strings.

{{ "hello world" | url_encode }}
<!-- Output: hello%20world -->

escape​

Escapes HTML characters.

{{ "<script>" | escape }}
<!-- Output: &lt;script&gt; -->

strip_html​

Removes HTML tags.

{{ "<p>Hello</p>" | strip_html }}
<!-- Output: Hello -->

strip_newlines​

Removes newline characters.

{{ "Line 1\nLine 2" | strip_newlines }}
<!-- Output: Line 1Line 2 -->

newline_to_br​

Converts newlines to <br> tags.

{{ "Line 1\nLine 2" | newline_to_br }}
<!-- Output: Line 1<br>Line 2 -->

Number Filters​

Arithmetic​

plus / minus / times / divided_by​

Basic arithmetic operations.

{{ 10 | plus: 5 }}
<!-- Output: 15 -->

{{ 10 | minus: 3 }}
<!-- Output: 7 -->

{{ 5 | times: 4 }}
<!-- Output: 20 -->

{{ 20 | divided_by: 4 }}
<!-- Output: 5 -->

modulo​

Returns remainder of division.

{{ 10 | modulo: 3 }}
<!-- Output: 1 -->

Rounding​

round / ceil / floor​

Rounding operations.

{{ 3.7 | round }}
<!-- Output: 4 -->

{{ 3.2 | ceil }}
<!-- Output: 4 -->

{{ 3.8 | floor }}
<!-- Output: 3 -->

abs​

Absolute value.

{{ -5 | abs }}
<!-- Output: 5 -->

Array Filters​

Access​

first / last​

Get first or last element.

{% assign items = "one,two,three" | split: "," %}
{{ items | first }}
<!-- Output: one -->

{{ items | last }}
<!-- Output: three -->

size​

Get array length.

{% assign items = "one,two,three" | split: "," %}
{{ items | size }}
<!-- Output: 3 -->

slice​

Get array slice.

{% assign items = "one,two,three,four" | split: "," %}
{{ items | slice: 1, 2 }}
<!-- Output: two,three -->

Manipulation​

sort​

Sort array.

{% assign items = "c,a,b" | split: "," %}
{{ items | sort | join: "," }}
<!-- Output: a,b,c -->

reverse​

Reverse array.

{% assign items = "one,two,three" | split: "," %}
{{ items | reverse | join: "," }}
<!-- Output: three,two,one -->

uniq​

Remove duplicates.

{% assign items = "a,b,a,c" | split: "," %}
{{ items | uniq | join: "," }}
<!-- Output: a,b,c -->

map​

Extract property from objects.

{% assign products = collection.products %}
{{ products | map: "name" | join: ", " }}

where​

Filter array by property value.

{% assign available = products | where: "available", true %}

Date Filters​

date​

Format dates.

{{ "2024-01-15" | date: "%B %d, %Y" }}
<!-- Output: January 15, 2024 -->

{{ "now" | date: "%Y-%m-%d" }}
<!-- Output: Current date -->

Format Codes:

  • %Y - Year (4 digits)
  • %y - Year (2 digits)
  • %m - Month (01-12)
  • %d - Day (01-31)
  • %H - Hour (00-23)
  • %M - Minute (00-59)
  • %S - Second (00-59)
  • %B - Full month name
  • %b - Abbreviated month name
  • %A - Full weekday name
  • %a - Abbreviated weekday name

time_ago / time_until​

Relative time.

{{ "2024-01-01" | time_ago }}
<!-- Output: 2 weeks ago -->

{{ "2024-12-31" | time_until }}
<!-- Output: in 11 months -->

Money Filters​

money​

Format currency (basic).

{{ 1000 | money }}
<!-- Output: ₹1,000.00 -->

money_with_currency​

Format with currency symbol.

{{ 1000 | money_with_currency }}
<!-- Output: ₹1,000.00 INR -->

money_with_settings​

Format using store settings.

{{ 1000 | money_with_settings }}
<!-- Output: Formatted according to store currency settings -->

URL Filters​

product_url / collection_url / page_url​

Generate URLs.

{{ product | product_url }}
<!-- Output: /products/product-handle -->

{{ collection | collection_url }}
<!-- Output: /collections/collection-handle -->

{{ page | page_url }}
<!-- Output: /pages/page-handle -->

img_url​

Generate image URLs with size.

{{ product.image | img_url: "large" }}
<!-- Output: /images/product-image-large.jpg -->

Size Options:

  • small - 100x100
  • medium - 300x300
  • large - 600x600
  • grande - 1024x1024
  • original - Original size

img_tag​

Generate complete image tag.

{{ product.image | img_tag: "Product Image", "large" }}
<!-- Output: <img src="..." alt="Product Image" class="large"> -->

asset_url​

Generate asset URLs with versioning.

{{ "theme.css" | asset_url | stylesheet_tag }}
<!-- Output: <link rel="stylesheet" href="/assets/theme.css?v=123"> -->

Utility Filters​

default​

Provide default value if empty.

{{ product.description | default: "No description available" }}

json​

Convert to JSON string.

{{ product | json }}
<!-- Output: {"id":"123","name":"Product"} -->

pluralize​

Pluralize words.

{{ 1 | pluralize: "item", "items" }}
<!-- Output: item -->

{{ 2 | pluralize: "item", "items" }}
<!-- Output: items -->

handleize​

Convert to URL-friendly handle.

{{ "Hello World" | handleize }}
<!-- Output: hello-world -->

highlight​

Highlight search terms.

{{ "Hello World" | highlight: "World" }}
<!-- Output: Hello <mark>World</mark> -->

Chaining Filters​

Filters can be chained to create complex transformations:

Basic Chaining​

{{ product.name | upcase | truncate: 20 }}
{{ product.price | money | prepend: "Price: " }}

Complex Chaining Examples​

<!-- Format product name: uppercase, truncate, add ellipsis -->
{{ product.name | upcase | truncate: 30, "..." }}

<!-- Format price with currency and prefix -->
{{ product.price | money | prepend: "$" | append: " USD" }}

<!-- Clean and format description -->
{{ product.description | strip_html | truncatewords: 50 | capitalize }}

<!-- Format date with custom format -->
{{ product.created_at | date: "%B %d, %Y" | upcase }}

<!-- Process product tags -->
{{ product.tags | join: ", " | capitalize | prepend: "Tags: " }}

<!-- Format image URL with size -->
{{ product.image | img_url: 'large' | prepend: "https://cdn.example.com" }}

Chaining Best Practices​

  1. Order Matters: Filters execute left to right
{{ "hello world" | upcase | capitalize }}
<!-- Output: HELLO WORLD (upcase first, then capitalize does nothing) -->

{{ "hello world" | capitalize | upcase }}
<!-- Output: HELLO WORLD (capitalize first, then upcase) -->
  1. Avoid Over-Chaining: Keep chains readable
<!-- ❌ Too complex -->
{{ product.name | upcase | strip | truncate: 20 | replace: " ", "-" | downcase }}

<!-- ✅ Better: Break into steps -->
{% assign clean_name = product.name | strip | truncate: 20 %}
{{ clean_name | replace: " ", "-" | downcase }}

Filter Performance Tips​

1. Cache Filter Results​

❌ Repeated filtering:

{% for product in products %}
  {{ product.name | upcase | truncate: 20 }}
  {{ product.name | upcase | truncate: 20 }}  <!-- Duplicate -->
{% endfor %}

✅ Cache results:

{% for product in products %}
  {% assign product_title = product.name | upcase | truncate: 20 %}
  <h3>{{ product_title }}</h3>
  <p>{{ product_title }}</p>
{% endfor %}

2. Avoid Complex Filters in Loops​

❌ Complex filter in loop:

{% for product in products %}
  {{ product.description | strip_html | truncatewords: 50 | capitalize | replace: "Product", "Item" }}
{% endfor %}

✅ Pre-process or use snippet:

{% for product in products %}
  {% render 'product-description', product: product %}
{% endfor %}

3. Use Appropriate Filters​

❌ Inefficient:

{{ product.price | times: 100 | divided_by: 100 | money }}

✅ Use built-in:

{{ product.price | money }}

Custom Filter Creation Guide​

Creating Custom Filters (Backend)​

Custom filters are created in the Liquid helper service:

// services/liquid-helper-service.js
liquid.registerFilter('custom_format', (value, format) => {
  // Custom formatting logic
  return formattedValue;
});

Using Custom Filters​

{{ product.name | custom_format: 'uppercase' }}

Common Custom Filter Examples​

  1. Format Phone Number:
liquid.registerFilter('phone_format', (value) => {
  const cleaned = value.replace(/\D/g, '');
  return `(${cleaned.slice(0,3)}) ${cleaned.slice(3,6)}-${cleaned.slice(6)}`;
});
  1. Relative Time:
liquid.registerFilter('relative_time', (date) => {
  const now = new Date();
  const diff = now - new Date(date);
  const days = Math.floor(diff / (1000 * 60 * 60 * 24));
  return `${days} days ago`;
});
  1. Truncate by Characters:
liquid.registerFilter('truncate_chars', (value, length) => {
  if (value.length <= length) return value;
  return value.slice(0, length) + '...';
});

Filter Testing Examples​

Testing String Filters​

{% comment %} Test various string inputs {% endcomment %}
Input: "Hello World"
- upcase: {{ "Hello World" | upcase }}
- downcase: {{ "Hello World" | downcase }}
- capitalize: {{ "Hello World" | capitalize }}
- truncate: {{ "Hello World" | truncate: 5 }}

Testing Number Filters​

{% comment %} Test number operations {% endcomment %}
Price: {{ 99.99 }}
- plus 10: {{ 99.99 | plus: 10 }}
- minus 10: {{ 99.99 | minus: 10 }}
- times 2: {{ 99.99 | times: 2 }}
- divided_by 3: {{ 99.99 | divided_by: 3 }}
- round: {{ 99.99 | round }}

Testing Array Filters​

{% assign test_array = "apple,banana,cherry" | split: "," %}
Array: {{ test_array | json }}
- first: {{ test_array | first }}
- last: {{ test_array | last }}
- size: {{ test_array | size }}
- join: {{ test_array | join: " | " }}

Testing Edge Cases​

{% comment %} Test with null/empty values {% endcomment %}
Null value: {{ null | default: "Default" }}
Empty string: {{ "" | default: "Default" }}
Undefined: {{ undefined | default: "Default" }}

{% comment %} Test with invalid types {% endcomment %}
String as number: {{ "abc" | plus: 1 }}
Number as string: {{ 123 | upcase }}

Filter Reference Quick Lookup​

String Filters​

FilterDescriptionExample
upcaseUppercase{{ "hello" | upcase }} → HELLO
downcaseLowercase{{ "HELLO" | downcase }} → hello
capitalizeCapitalize words{{ "hello world" | capitalize }} → Hello World
truncateTruncate string{{ "long text" | truncate: 5 }} → long ...
truncatewordsTruncate words{{ "long text here" | truncatewords: 2 }} → long text...
stripRemove whitespace{{ " hello " | strip }} → hello
replaceReplace text{{ "hello" | replace: "l", "L" }} → heLLo
removeRemove text{{ "hello" | remove: "l" }} → heo
prependAdd before{{ "world" | prepend: "hello " }} → hello world
appendAdd after{{ "hello" | append: " world" }} → hello world

Number Filters​

FilterDescriptionExample
plusAdd{{ 5 | plus: 3 }} → 8
minusSubtract{{ 10 | minus: 3 }} → 7
timesMultiply{{ 5 | times: 3 }} → 15
divided_byDivide{{ 10 | divided_by: 3 }} → 3.33...
moduloModulo{{ 10 | modulo: 3 }} → 1
roundRound{{ 3.7 | round }} → 4
ceilCeiling{{ 3.2 | ceil }} → 4
floorFloor{{ 3.7 | floor }} → 3
absAbsolute{{ -5 | abs }} → 5

Array Filters​

FilterDescriptionExample
firstFirst item{{ array | first }}
lastLast item{{ array | last }}
sizeArray size{{ array | size }}
sliceSlice array{{ array | slice: 0, 3 }}
sortSort array{{ array | sort }}
reverseReverse{{ array | reverse }}
uniqUnique items{{ array | uniq }}
joinJoin items{{ array | join: ", " }}
whereFilter items{{ products | where: "available", true }}

Money Filters​

FilterDescriptionExample
moneyFormat money{{ 1000 | money }} → $10.00
money_with_currencyWith currency{{ 1000 | money_with_currency }} → $10.00 USD
money_with_settingsWith settings{{ 1000 | money_with_settings }}

URL Filters​

FilterDescriptionExample
product_urlProduct URL{{ product | product_url }}
collection_urlCollection URL{{ collection | collection_url }}
page_urlPage URL{{ page | page_url }}
img_urlImage URL{{ image | img_url: 'large' }}
asset_urlAsset URL{{ 'theme.css' | asset_url }}

Best Practices​

  1. Default Values: Use default filter for optional values
  2. Error Handling: Validate data before applying filters
  3. Performance: Avoid complex filter chains in loops
  4. Readability: Use descriptive filter names
  5. Testing: Test filters with various input types
  6. Chaining: Keep filter chains readable and logical
  7. Caching: Cache expensive filter operations
  8. Documentation: Document custom filters

Next Steps​