Free guide · tags, filters and objects · about 60 minutes

Shopify Liquid cheat sheet, explained

Shopify's cheat sheet gives you the names. This page tells you what each one is for in a real store, when you use it, and shows a short example.

How to use this page

Shopify's Liquid cheat sheet (shopify.com/partners/shopify-cheat-sheet (opens in a new tab)) lists everything you can use in a theme: tags, filters and objects. A list of names is hard to learn from. So for each one, this page tells you three things:

• What it is, in one simple line.
• Real use: where you actually use it in a store.
• Example: a short piece of code you can copy.

Think of the cheat sheet as a toolbox. This page opens the box and shows you what each tool is for.

How to try the examples

Open Shopify admin → Online Store → Themes → Horizon → Customize, add a Custom Liquid section to the right page (product page for product examples, cart page for cart examples), and paste the code.

Handles

A handle is the web-friendly name of something in your store. It is all small letters, with dashes instead of spaces.

Think of it as a house address. The house name can be fancy, but the address must be simple and unique.

Real use: handles are in every URL (/products/masala-chai-500g), and you use them in Liquid to fetch one specific thing:

{{ collections['summer-sale'].title }}
{{ pages['about-us'].content }}

When: you need one fixed collection, page or menu in a section, for example a "Best sellers" row.

Basics (quick list)

All of these are explained with examples on the Liquid page. Here is how they show up in a store.

Tags

Conditional tags (quick list)

Details and examples: Liquid page, control flow.

form

Creates a real Shopify form, with the right address and hidden fields, so Shopify knows what to do with it.

Real use: add to cart, contact us, newsletter signup, customer login and register, product reviews (blog comments), address book.

When: any time the shopper sends something to Shopify. Never write these forms by hand; the hidden fields are easy to get wrong.

{% form 'contact' %}
  {% if form.posted_successfully? %}
    <p>Thanks! We will reply within a day.</p>
  {% endif %}
  {{ form.errors | default_errors }}
  <label for="c-email">Email</label>
  <input id="c-email" type="email" name="contact[email]" required>
  <label for="c-msg">Message</label>
  <textarea id="c-msg" name="contact[body]"></textarea>
  <button>Send</button>
{% endform %}

Common form types: 'product' (add to cart, needs the product), 'contact', 'customer' (newsletter), 'customer_login', 'create_customer', 'customer_address', 'new_comment' (needs the article), 'localization' (country and language picker).

style

Like an HTML <style> tag, but the theme editor updates it live when the merchant changes a setting.

Real use: colours or sizes that come from section settings.

When: your CSS needs a value from a setting. Plain CSS cannot read Liquid; {% style %} can.

{% style %}
  .announcement-{{ section.id }} {
    background: {{ section.settings.background }};
    color: {{ section.settings.text_color }};
  }
{% endstyle %}
<div class="announcement-{{ section.id }}">{{ section.settings.text }}</div>

Using section.id in the class keeps two copies of the section from changing each other's colours.

Iteration tags (quick list)

Details: Liquid page, iteration.

paginate

Splits a long list into pages. Shopify only lets you loop over 50 items at a time, so big lists need it.

Real use: collection pages ("Page 1, 2, 3"), search results, blog post lists, customer order history.

When: a list can be longer than about 50 items.

{% paginate collection.products by 12 %}
  {% for product in collection.products %}
    <p>{{ product.title }}</p>
  {% endfor %}
  {{ paginate | default_pagination }}
{% endpaginate %}

default_pagination prints ready-made "Previous 1 2 3 Next" links. Inside, the paginate object tells you paginate.current_page, paginate.pages and more, if you want to build your own buttons.

Syntax tags (quick list)

Details: Liquid page, template tags.

Theme tags

These connect the files of a theme together.

{% for product in collection.products %}
  {% render 'product-card', product: product, show_vendor: true %}
{% endfor %}

Variable tags (quick list)

Details: Liquid page, variables.

Filters

Array filters (quick list)

Details: Liquid page, list filters.

Cart filters

item_count_for_variant

Tells you how many of this variant are already in the cart.

Real use: show "2 already in your cart" on the product page, or stop a shopper going over a buying limit. Horizon uses it next to the quantity box.

{%- assign in_cart = cart | item_count_for_variant: product.selected_or_first_available_variant.id -%}
{% if in_cart > 0 %}<p>{{ in_cart }} already in your cart</p>{% endif %}

Collection filters

These build links for collection pages.

Color filters

Change colours with Liquid, so one brand colour setting can make lighter, darker or see-through versions.

Real use: the merchant picks one brand colour in settings; you make the hover colour, the light background and readable text from it automatically.

{{ '#7ab55c' | color_to_rgb }}
{{ '#7ab55c' | color_modify: 'alpha', 0.15 }}

rgb(122, 181, 92)
rgba(122, 181, 92, 0.15)

Pick text colour based on brightness (save it first, filters do not work inside if):

{%- assign brightness = section.settings.background | color_brightness -%}
<div style="background: {{ section.settings.background }}; color: {% if brightness > 128 %}#000{% else %}#fff{% endif %}">
  Sale
</div>

Customer filters

{% if customer %}
  Hi {{ customer.first_name }} · {{ 'Log out' | customer_logout_link }}
{% else %}
  {{ 'Log in' | customer_login_link }}
{% endif %}

Default filters

<h2>{{ section.settings.heading | default: 'Our best sellers' }}</h2>
{{ form.errors | default_errors }}

Font filters

Merchants pick fonts in Theme settings → Typography. These filters turn that choice into working CSS.

{%- assign heading_bold = settings.type_heading_font | font_modify: 'weight', 'bold' -%}
{% style %}
  {{ settings.type_heading_font | font_face: font_display: 'swap' }}
  {{ heading_bold | font_face: font_display: 'swap' }}
  h1, h2 { font-family: {{ settings.type_heading_font.family }}, {{ settings.type_heading_font.fallback_families }}; }
{% endstyle %}

font_display: 'swap' shows the text right away in a backup font, then swaps. See the speed guide.

Format filters

Shopify's date also has ready-made formats that follow the store language: {{ article.published_at | date: format: 'abbreviated_date' }}.

HTML filters

These write HTML tags for you.

{{ 'Shop all teas' | link_to: '/collections/teas' }}
{{ 'custom.js' | asset_url | script_tag }}
{{ item.title | highlight: search.terms }}
{%- if section.settings.image == blank -%}{{ 'image' | placeholder_svg_tag: 'placeholder' }}{%- endif -%}

Hosted file filters

<script src="{{ 'custom.js' | asset_url }}" defer></script>
<a href="{{ 'size-chart.pdf' | file_url }}" target="_blank">Size chart (PDF)</a>

Localization filters

<button>{{ 'products.product.add_to_cart' | t }}</button>
{{ customer.default_address | format_address }}

Math filters (quick list)

Details: Liquid page, number filters.

Media filters

{% for media in product.media %}
  {% case media.media_type %}
    {% when 'image' %}
      {{ media | image_url: width: 1000 | image_tag: loading: 'lazy' }}
    {% when 'video' %}
      {{ media | video_tag: controls: true }}
    {% when 'external_video' %}
      {{ media | external_video_tag }}
    {% else %}
      {{ media | media_tag }}
  {% endcase %}
{% endfor %}

Metafield filters

{{ product.metafields.custom.care_instructions | metafield_tag }}
{{ product.metafields.custom.fabric | metafield_text }}

Money filters

Prices in Liquid are in the smallest unit (paise). These filters turn them into readable prices in the store's format.

{{ product.price | money }}
{{ cart.total_price | money_with_currency }}

Payment filters

{% for type in shop.enabled_payment_types %}
  {{ type | payment_type_svg_tag: class: 'payment-icon' }}
{% endfor %}

String filters

The everyday text filters (append, capitalize, downcase, upcase, escape, newline_to_br, prepend, remove, replace, slice, split, strip, strip_html, truncate, url_encode…) are explained on the Liquid page. Here are the ones Shopify adds.

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

3 items in your cart

Objects

Objects are the store data Liquid can read: the product, the cart, the customer, the settings. You print them with double curly braces, and read their details (called properties) with a dot: product.title, cart.item_count.

Some objects are available everywhere (like shop and cart). Others only on their page (like product on a product page, collection on a collection page). In a Horizon block, use closest.product and closest.collection to get the nearest one.

The most used objects

product

One product. Available on product pages, and in loops like for product in collection.products.

variant

One version of a product, like "Masala Chai / 500g".

collection

A group of products. Available on collection pages, or by handle: collections['teas'].

cart

The shopper's cart. Available everywhere.

customer

The logged-in customer. Empty if nobody is logged in, so always check {% if customer %} first.

shop

Your store's details. Available everywhere.

settings

The Theme settings the merchant chose in the theme editor (colours, fonts, logo, social links).

Real use: {{ settings.logo }}, settings.type_body_font, social links in the footer. The names come from config/settings_schema.json.

section and block

Inside a section file, section is that section; inside a block, block is that block.

{% for block in section.blocks %}
  <div {{ block.shopify_attributes }}>
    <h3>{{ block.settings.question }}</h3>
    <p>{{ block.settings.answer }}</p>
  </div>
{% endfor %}

request and routes

<a href="{{ routes.cart_url }}">Cart ({{ cart.item_count }})</a>
{% if request.page_type == 'product' %}<script src="{{ 'product-extra.js' | asset_url }}" defer></script>{% endif %}

All objects, grouped

Every object in the cheat sheet, with what it is and where you use it.

Page and layout objects

Store-wide objects

Product objects

Collection, search and navigation objects

Cart, checkout and order objects

Customer and B2B objects

Content objects

Theme building objects

robots.txt objects

robots, group, rule, sitemap and user_agent are only used in the templates/robots.txt.liquid file, which tells Google which pages to skip.

Real use: block search engines from crawling a private or duplicate area of the store. When: rarely, and carefully; a mistake here can hide the whole store from Google.

Quick recap

• Handles are web-friendly names: masala-chai-500g. Use them to fetch one fixed collection, page or menu.
• Tags Shopify adds: form (all store forms), style (CSS from settings, live in the editor), paginate (long lists), layout, render, sections, javascript, stylesheet.
• Filters Shopify adds: money, images and media, fonts, colours, links, translations (t), metafields, payments.
• Objects are the store data: product, variant, collection, cart, customer, shop, settings, section, block, request, routes, and many more.
• Old items: use image_url (not img_url), render (not include), the localization form (not currency_selector), checkout extensions (not checkout.liquid).

Try it yourself

On the product page, add a Custom Liquid block inside Product information that shows:

By Chai Corner · Tea · ₹250 · 2 already in your cart

The brand and type must be links, the price must use the store's money format without trailing zeros, and the last part shows only if this variant is already in the cart.

Hints: link_to_vendor, link_to_type, money_without_trailing_zeros, item_count_for_variant. In a block, use closest.product.

{%- liquid
  assign p = closest.product
  assign v = p.selected_or_first_available_variant
  assign in_cart = cart | item_count_for_variant: v.id
-%}
<p>
  By {{ p.vendor | link_to_vendor }} · {{ p.type | link_to_type }} · {{ v.price | money_without_trailing_zeros }}
  {%- if in_cart > 0 %} · {{ in_cart }} already in your cart{% endif %}
</p>

Learn the core language first? Read Liquid explained simply. Want to practise on your own store with me? Join a live class.