Utility Filters

Utility filters handle common tasks that do not fit into a single category. They cover fallback values, data conversion, translation, and HTML generation.

default

Provide a fallback value when a variable is nil, false, or an empty string:

{{ product.vendor | default: 'Unknown' }}

If product.vendor has a value, it is used. If it is missing or blank, the output is Unknown.

This is useful for optional fields that might not be set:

{{ product.custom_label | default: product.title }}

json

Convert a value or object to a JSON string:

<script>
  var product = {{ product | json }};
</script>

Output:

<script>
  var product = {"title":"Classic Tee","price":2999,"available":true};
</script>

This is the safest way to pass data from your templates into JavaScript. The filter handles escaping so the JSON is always valid.

t (translation)

Look up a translated string from your theme's locale files:

{{ 'cart.empty_message' | t }}

Output depends on the visitor's language. For English: Your cart is empty. For French: Votre panier est vide.

The key (cart.empty_message) maps to a value in the theme's translation files. See the Themes section for how locale files work.

With variables

Pass dynamic values into a translation string:

{{ 'cart.item_count' | t: count: cart.item_count }}

If the translation string is You have {{ count }} items, the output is You have 3 items.

weight_with_unit

Format a weight value with its unit label:

{{ variant.weight | weight_with_unit }}

Output: 250 g or 1.5 kg, depending on the store's weight unit setting.

This saves you from writing conditional logic to pick the right unit.

link_to

Wrap text in an anchor tag:

{{ 'View all products' | link_to: '/collections/all' }}

Output:

<a href="/collections/all">View all products</a>

With attributes

Add a CSS class or other attributes:

{{ 'View all' | link_to: '/collections/all', class: 'btn' }}

Output:

<a href="/collections/all" class="btn">View all</a>

highlight

Wrap matching text in <mark> tags. This is useful for showing search results where the query terms are highlighted:

{{ result.title | highlight: search.terms }}

If the product title is Classic Gold Ring and the search term is gold, the output is:

Classic <mark>Gold</mark> Ring

The match is case-insensitive. The original casing of the text is kept.

default_pagination

Render a standard set of page navigation links for a paginated collection:

{% paginate collection.products by 24 %}
  {% for product in collection.products %}
    {% render 'product-card' with product %}
  {% endfor %}

  {{ paginate | default_pagination }}
{% endpaginate %}

The output is a series of links: Previous, numbered pages, and Next. The current page is marked with an aria-current attribute. This filter saves you from building pagination HTML by hand.

For custom pagination, use the paginate object properties instead. See the Template Tags page for details.

default_errors

Render the standard error message list for a form:

{% form 'create_customer' %}
  {{ form.errors | default_errors }}
  <input type="email" name="email" />
  <button type="submit">Register</button>
{% endform %}

When the form has validation errors, this filter outputs an unordered list with each error message. When there are no errors, nothing is rendered.

Practical examples

Safe JavaScript data

Pass product data to a client-side script without worrying about escaping:

<div data-product="{{ product | json | escape }}">
  {{ product.title }}
</div>

Fallback images

Use a placeholder when a product has no image:

{% assign image = product.featured_image | default: 'placeholder.png' %}
<img src="{{ image | img_url: '400x400' }}" alt="{{ product.title }}" />

Translated buttons

<button type="submit">
  {{ 'product.add_to_cart' | t }}
</button>

The button text changes based on the visitor's language. No conditional logic needed in the template.