Skip to content
Tutorials Center
My learning

Topics

Lesson 11 of 61 ยท Liquid Basics

Shopify Filters: Money, Images, URLs and Assets

Learn Shopify-specific Liquid filters: money, image_url and image_tag, asset_url, stylesheet_tag, t, date, json, handle and URL filters, plus deprecated filters to avoid.

The standard filters from the previous lesson work in any Liquid engine. Shopify adds its own, because stores need things generic Liquid does not know about: formatting a price in the shop's currency, building a CDN image URL at the right size, finding a file in the theme's assets folder, or translating a string into the visitor's language.

This lesson walks through the Shopify filters you will meet in every theme, shows what each one produces, and lists the old filters you should replace. The filters shown target current Online Store 2.0 themes. Liquid output does not depend on an Admin API version, but Shopify does retire filters over time, so treat the deprecated list as something to re-check against the Liquid reference when you start a new project.

Shopify filters only exist on Shopify, so the real theme code in this lesson is read-only. The runnable examples are stand-ins: they implement money formatting, handles and an image tag in JavaScript with made-up CDN URLs, so you can see how the pieces fit together. They are not Shopify's code, and real URLs, parameters and edge cases differ.

Money filters

Product prices, compare-at prices, cart totals and discounts are all stored as integers in the smallest currency unit (cents for US dollars). Never print them raw. The money filters turn the integer into a formatted string using the store's currency settings.

Filter Typical result (US store)
{{ product.price | money }} $129.00
{{ product.price | money_with_currency }} $129.00 USD
{{ product.price | money_without_currency }} 129.00
{{ product.price | money_without_trailing_zeros }} $129

The exact text comes from the merchant's format settings, and a German store would show something like 129,00 โ‚ฌ. That is why you should use these filters instead of dividing by 100 yourself. Customers who switch market or currency also get prices in their own currency without any extra code.

The first example below is a stand-in that shows how one integer turns into different strings depending on a store's format.

JS Money formats, as a stand-in

Press Run (or Ctrl + Enter) to see the console output here.

No output.

What is real and what is not? Real Shopify reads the formats from the store and handles rounding rules per currency. The format placeholders such as {{amount}} and {{amount_with_comma_separator}} really exist in Shopify's currency settings; the code that fills them is our own simplified version.

Images: image_url and image_tag

Images are objects (product.featured_image, image, media.preview_image, a section.settings.image picker value), not plain URLs. Two filters work together:

LIQUID
{{ product.featured_image | image_url: width: 600 }}

{{ product.featured_image
  | image_url: width: 600
  | image_tag: widths: '300, 600, 900', sizes: '(min-width: 768px) 50vw, 100vw', class: 'card__image' }}
  • image_url returns a URL on Shopify's CDN. Pass the width (and optionally height) you want; Shopify serves a resized copy, so you never download a 4,000-pixel photo for a 300-pixel card. The largest allowed size is 5,760 pixels.
  • image_tag takes that URL and builds a full <img> element with src, alt (from the image's alt text unless you pass your own), dimensions, a srcset and lazy loading. Options such as widths, sizes, class, alt and loading let you tune it, and pass loading: 'eager' for the main image at the top of the page.
flowchart LR
    I["Image object<br/>product.featured_image"] --> U["image_url: width: 600"]
    U --> C["CDN URL for a 600px copy"]
    C --> T["image_tag: widths, sizes, class"]
    T --> H["img element with src, srcset,<br/>sizes, width, height, alt"]

image_url makes the URL, image_tag turns it into complete markup.

Responsive images, srcset and sizes are explained in depth in Product Media: Images, Video and 3D. The second stand-in below builds the same kind of output with a fake CDN so you can read an <img> with its srcset.

Assets: asset_url, stylesheet_tag and friends

Files in the theme's assets folder are served from Shopify's CDN. You reference them with asset_url:

LIQUID
<link rel="stylesheet" href="{{ 'base.css' | asset_url }}">
{{ 'base.css' | asset_url | stylesheet_tag }}
<script src="{{ 'theme.js' | asset_url }}" defer></script>
<img src="{{ 'logo.svg' | asset_url }}" alt="" width="120" height="40">

stylesheet_tag wraps the URL in a <link rel="stylesheet"> element. For JavaScript, write the <script> tag yourself with defer or type="module": the old script_tag filter has no way to add those attributes and is deprecated.

Files that merchants upload under Content > Files are not in assets; they have their own filter, file_url:

LIQUID
<a href="{{ 'size-chart.pdf' | file_url }}">Download the size chart</a>

asset_url adds a version parameter that changes when you update the file, so browsers fetch the new version without you renaming it.

Strings, dates and data: t, date and json

LIQUID
{{ 'products.product.add_to_cart' | t }}
{{ 'cart.item_count' | t: count: cart.item_count }}
{{ article.published_at | date: '%B %d, %Y' }}
{{ 'now' | date: '%Y' }}
<script type="application/json" id="product-json">{{ product | json }}</script>
  • t looks up a translation key in the locale files and returns the text for the visitor's language. Variables and plural counts are passed as named arguments. Locale files and pluralization are the subject of Translations, Markets and Localization.
  • date formats a date with strftime codes (%B is the month name, %d the day, %Y the year). The special value 'now' means "when this page was rendered", which is fine for a copyright year but must not be used for logic that needs to be exact, because Shopify caches pages.
  • json turns an object, array or string into JSON. It is the standard way to hand data to JavaScript. Be careful with user text inside script tags; Security in Themes shows the risks.

URL and handle filters

A handle is the URL-friendly name of a product, collection, page or blog (trail-jacket). The handle filter (also spelled handleize) turns any string into one:

LIQUID
<div class="card card--{{ product.type | handle }}">

For a product type of Rain Jackets, the class becomes card--rain-jackets.

Handles are mostly useful for CSS classes and element ids built from titles, or for looking up a linked list (linklists[block.settings.menu]) by handle. Some other URL helpers:

LIQUID
{{ product.url | within: collection }}
{{ product.title | link_to: product.url }}
{{ search.terms | url_encode }}

within turns /products/trail-jacket into /collections/jackets/products/trail-jacket when you pass the collection the visitor came from. It keeps the visitor's collection in the product URL so breadcrumbs and "next product" links can still work. Prefer building links with product.url and routes such as routes.cart_url over typing paths, so the theme works when a store uses a different locale or market path.

The second example is a stand-in for handle, image_url and image_tag. It uses a made-up CDN, but the structure of the <img> mirrors what you would see in the browser's source view.

JS handle, image_url and image_tag, as stand-ins

Press Run (or Ctrl + Enter) to see the console output here.

No output.

Deprecated filters to avoid

Older themes (and many tutorials) still use filters that Shopify has replaced. Theme Check flags them. When you see one, upgrade it:

Deprecated Use instead
img_url image_url
img_tag image_tag
product_img_url, collection_img_url, article_img_url image_url on the image object
script_tag a <script src="{{ 'x.js' | asset_url }}" defer> tag
the include tag the render tag, see Snippets and the render Tag

Do a search for these names in your theme when you inherit one; the upgrade path is described in Migrating Legacy Themes to Online Store 2.0.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. A product costs 12900 in product.price. Which is the best way to print it?

    money applies the store's currency format, separators and symbol. Dividing by 100 yourself ignores those settings and markets.
  2. 2. Which filter pair builds a complete responsive img element from an image object?

    image_url creates a CDN URL for the size you ask for, and image_tag turns it into an img element with srcset, dimensions and alt text.
  3. 3. Where do you reference a theme's own CSS file base.css?

    Files in the theme's assets folder use asset_url. file_url is for files uploaded under Content > Files.
  4. 4. Why is script_tag discouraged?

    Write the script element yourself with asset_url so you can control loading attributes.

Summary

  • Prices are integers in cents; print them with money, money_with_currency, money_without_currency or money_without_trailing_zeros.
  • image_url makes a CDN URL at a requested width and image_tag turns it into a complete <img>.
  • asset_url points to files in assets, stylesheet_tag wraps a stylesheet URL, and file_url serves uploaded files.
  • t, date and json handle translations, dates and data for JavaScript; handle and within build URL-friendly names and links.
  • Replace img_url, img_tag, script_tag and friends with their modern equivalents.

Next: The Global Objects You Use Most