Shopify Liquid Themes

Shopify Liquid Themes

Theme Architecture

.
├── sections/    # Full-width page modules with {% schema %} — hero, product grid, testimonials
├── blocks/      # Nestable components with {% schema %} — slides, feature items, text blocks
├── snippets/    # Reusable fragments via {% render %} — buttons, icons, image helpers
├── layout/      # Page wrappers (must include {{ content_for_header }} and {{ content_for_layout }})
├── templates/   # JSON files defining which sections appear on each page type
├── config/      # Global theme settings (settings_schema.json, settings_data.json)
├── locales/     # Translation files (en.default.json, fr.json, etc.)
└── assets/      # Static CSS, JS, images (prefer {% stylesheet %}/{% javascript %} instead)

When to use what

Liquid Syntax

Delimiters

• {{ ... }} — Output (prints a value)
• {{- ... -}} — Output with whitespace trimming
• {% ... %} — Logic tag (if, for, assign) — prints nothing
• {%- ... -%} — Logic tag with whitespace trimming

Operators

Comparison: ==, !=, >, <, >=, <= Logical: and, or, contains

Critical Gotchas

1. No parentheses in conditions — use nested {% if %} instead 2. No ternary — always use {% if cond %}value{% else %}other{% endif %} 3. `for` loops max 50 iterations — use {% paginate %} for larger arrays 4. `contains` only works with strings — can't check objects in arrays 5. `{% stylesheet %}`/`{% javascript %}` don't render Liquid — no Liquid inside them 6. Snippets can't access outer-scope variables — pass them as render params 7. `include` is deprecated — always use {% render 'snippet_name' %} 8. `{% liquid %}` tag — multi-line logic without delimiters; use echo for output

Variables

{% assign my_var = 'value' %}
{% capture my_var %}computed {{ value }}{% endcapture %}
{% increment counter %}
{% decrement counter %}

Filter Quick Reference

Filters are chained with |. Output type of one filter feeds input of next.

Array: compact, concat, find, find_index, first, has, join, last, map, reject, reverse, size, sort, sort_natural, sum, uniq, where String: append, capitalize, downcase, escape, handleize, lstrip, newline_to_br, prepend, remove, replace, rstrip, slice, split, strip, strip_html, truncate, truncatewords, upcase, url_decode, url_encode Math: abs, at_least, at_most, ceil, divided_by, floor, minus, modulo, plus, round, times Money: money, money_with_currency, money_without_currency, money_without_trailing_zeros Color: color_brightness, color_darken, color_lighten, color_mix, color_modify, color_saturate, color_desaturate, color_to_hex, color_to_hsl, color_to_rgb Media: image_url, image_tag, video_tag, external_video_tag, media_tag, model_viewer_tag URL: asset_url, asset_img_url, file_url, shopify_asset_url HTML: link_to, script_tag, stylesheet_tag, time_tag, placeholder_svg_tag Localization: t (translate), format_address, currency_selector Other: date, default, json, structured_data, font_face, font_url, payment_button

Full details: language filters, HTML/media filters, commerce filters

Tags Quick Reference

Full details with syntax and parameters: references/tags.md

Objects Quick Reference

Global objects (available everywhere)

cart, collections, customer, localization, pages, request, routes, settings, shop, template, theme, linklists, images, blogs, articles, all_products, metaobjects, canonical_url, content_for_header, content_for_layout, page_title, page_description, handle, current_page

Page-specific objects

Full reference: commerce objects, content objects, tier 2, tier 3

Schema Tag

Sections and blocks require {% schema %} with a valid JSON object. Sections use section.settings.*, blocks use block.settings.*.

Section schema structure

{
  "name": "t:sections.hero.name",
  "tag": "section",
  "class": "hero-section",
  "limit": 1,
  "settings": [],
  "max_blocks": 16,
  "blocks": [{ "type": "@theme" }],
  "presets": [{ "name": "t:sections.hero.name" }],
  "enabled_on": { "templates": ["index"] },
  "disabled_on": { "templates": ["password"] }
}

Block schema structure

{
  "name": "t:blocks.slide.name",
  "tag": "div",
  "class": "slide",
  "settings": [],
  "blocks": [{ "type": "@theme" }],
  "presets": [{ "name": "t:blocks.slide.name" }]
}

Setting type decision table

visible_if pattern

{
  "visible_if": "{{ block.settings.layout == 'vertical' }}",
  "type": "select",
  "id": "alignment",
  "label": "t:labels.alignment",
  "options": [...]
}

Conditionally shows/hides a setting in the editor based on other setting values.

Block entry types

• { "type": "@theme" } — Accept any theme block
• { "type": "@app" } — Accept app blocks
• { "type": "slide" } — Accept only the slide block type

Full schema details and all 33 setting types: references/schema-and-settings.md

CSS & JavaScript

Per-component styles and scripts

Use {% stylesheet %} and {% javascript %} in sections, blocks, and snippets:

{% stylesheet %}
  .my-component { display: flex; }
{% endstylesheet %}

{% javascript %}
  console.log('loaded');
{% endjavascript %}

• One tag each per file — multiple {% stylesheet %} tags will error
• No Liquid inside — these tags don't process Liquid; use CSS variables or classes instead
• Only supported in sections/, blocks/, and snippets/

{% style %} tag (Liquid-aware CSS)

For dynamic CSS that needs Liquid (e.g., color settings that live-update in editor):

{% style %}
  .section-{{ section.id }} {
    background: {{ section.settings.bg_color }};
  }
{% endstyle %}

CSS patterns for settings

Single CSS property — use CSS variables:

<div style="--gap: {{ block.settings.gap }}px">

Multiple CSS properties — use CSS classes as select values:

<div class="{{ block.settings.layout }}">

LiquidDoc ({% doc %})

Required for: snippets (always), blocks (when statically rendered via {% content_for 'block' %})

{% doc %}
  Brief description of what this file renders.

  @param {type} name - Description of required parameter
  @param {type} [name] - Description of optional parameter (brackets = optional)

  @example
  {% render 'snippet-name', name: value %}
{% enddoc %}

Param types: string, number, boolean, image, object, array

Translations

Every user-facing string must use the t filter

<!-- Correct -->
<h2>{{ 'sections.hero.heading' | t }}</h2>
<button>{{ 'products.add_to_cart' | t }}</button>

<!-- Wrong — never hardcode strings -->
<h2>Welcome to our store</h2>

Variable interpolation

{{ 'products.price_range' | t: min: product.price_min | money, max: product.price_max | money }}

Locale file:

{
  "products": {
    "price_range": "From {{ min }} to {{ max }}"
  }
}

Locale file structure

locales/
├── en.default.json          # English translations (required)
├── en.default.schema.json   # Editor setting translations (required)
├── fr.json                  # French translations
└── fr.schema.json           # French editor translations

Key naming conventions

• Use snake_case and hierarchical keys (max 3 levels)
• Use sentence case for all text (capitalize first word only)
• Schema labels use t: prefix: "label": "t:labels.heading"
• Group by component: sections.hero.heading, blocks.slide.title

References

• Filters: language (77), HTML/media (45), commerce (30)
• Tag reference (30 tags)
• Objects: commerce (5), content (10), tier 2 (69), tier 3 (53)
• Schema & settings reference (33 types)
• Complete examples (snippet, block, section)

Complete Examples

Full, production-ready examples for each asset type. Use these as templates when generating Shopify Liquid theme code.

Snippet Example

Snippets live in snippets/, are rendered via {% render %}, and use {% doc %} for documentation. They have no {% schema %} tag.

File: `snippets/image.liquid`

{% doc %}
  Renders a responsive image that might be wrapped in a link.

  When `width`, `height` and `crop` are provided, the image will be rendered
  with a fixed aspect ratio.

  @param {image} image - The image to be rendered
  @param {string} [url] - An optional destination URL for the image
  @param {string} [css_class] - Optional class to be added to the image wrapper
  @param {number} [width] - The highest resolution width of the image to be rendered
  @param {number} [height] - The highest resolution height of the image to be rendered
  @param {string} [crop] - The crop position of the image

  @example
  {% render 'image', image: product.featured_image %}
  {% render 'image', image: product.featured_image, url: product.url %}
  {% render 'image',
    css_class: 'product__image',
    image: product.featured_image,
    url: product.url,
    width: 1200,
    height: 800,
    crop: 'center',
  %}
{% enddoc %}

{% liquid
  unless height
    assign width = width | default: image.width
  endunless

  if url
    assign wrapper = 'a'
  else
    assign wrapper = 'div'
  endif
%}

<{{ wrapper }}
  class="image {{ css_class }}"
  {% if url %}
    href="{{ url }}"
  {% endif %}
>
  {{ image | image_url: width: width, height: height, crop: crop | image_tag }}
</{{ wrapper }}>

{% stylesheet %}
  .image {
    display: block;
    position: relative;
    overflow: hidden;
    width: 100%;
    height: auto;
  }

  .image > img {
    width: 100%;
    height: auto;
  }
{% endstylesheet %}

{% javascript %}
  function doSomething() {
    // example
  }
  doSomething()
{% endjavascript %}

Key patterns:

• {% doc %} at the top documents params with types, optionality ([param]), and examples
• {% liquid %} block for multi-line logic (no delimiters needed per line)
• CSS variables for single-property settings, classes for multi-property
• One {% stylesheet %} and one {% javascript %} tag per file

Block Example: Text

Blocks live in blocks/, have {% schema %} for settings, and use {% doc %} when statically rendered.

File: `blocks/text.liquid`

{% doc %}
  Renders a text block.

  @example
  {% content_for 'block', type: 'text', id: 'text' %}
{% enddoc %}

<div
  class="text {{ block.settings.text_style }}"
  style="--text-align: {{ block.settings.alignment }}"
  {{ block.shopify_attributes }}
>
  {{ block.settings.text }}
</div>

{% stylesheet %}
  .text {
    text-align: var(--text-align);
  }
  .text--title {
    font-size: 2rem;
    font-weight: 700;
  }
  .text--subtitle {
    font-size: 1.5rem;
  }
{% endstylesheet %}

{% schema %}
{
  "name": "t:general.text",
  "settings": [
    {
      "type": "text",
      "id": "text",
      "label": "t:labels.text",
      "default": "Text"
    },
    {
      "type": "select",
      "id": "text_style",
      "label": "t:labels.text_style",
      "options": [
        { "value": "text--title", "label": "t:options.text_style.title" },
        { "value": "text--subtitle", "label": "t:options.text_style.subtitle" },
        { "value": "text--normal", "label": "t:options.text_style.normal" }
      ],
      "default": "text--title"
    },
    {
      "type": "text_alignment",
      "id": "alignment",
      "label": "t:labels.alignment",
      "default": "left"
    }
  ],
  "presets": [{ "name": "t:general.text" }]
}
{% endschema %}

Key patterns:

• {{ block.shopify_attributes }} required on the outermost block element
• CSS variable --text-align for single-property setting
• CSS class text--title for multi-property style variants
• All labels use t: translation keys
• select options use CSS class names as values when controlling multiple styles

Block Example: Group (Nested Blocks)

Group blocks accept child blocks via {% content_for 'blocks' %} and "blocks": [{ "type": "@theme" }].

File: `blocks/group.liquid`

{% doc %}
  Renders a group of blocks with configurable layout direction, gap and
  alignment.

  @example
  {% content_for 'block', type: 'group', id: 'group' %}
{% enddoc %}

<div
  class="group {{ block.settings.layout_direction }}"
  style="
    --padding: {{ block.settings.padding }}px;
    --alignment: {{ block.settings.alignment }};
  "
  {{ block.shopify_attributes }}
>
  {% content_for 'blocks' %}
</div>

{% stylesheet %}
  .group {
    display: flex;
    flex-wrap: nowrap;
    overflow: hidden;
    width: 100%;
  }
  .group--horizontal {
    flex-direction: row;
    justify-content: space-between;
    align-items: center;
    padding: 0 var(--padding);
  }
  .group--vertical {
    flex-direction: column;
    align-items: var(--alignment);
    padding: var(--padding) 0;
  }
{% endstylesheet %}

{% schema %}
{
  "name": "t:general.group",
  "blocks": [{ "type": "@theme" }],
  "settings": [
    {
      "type": "select",
      "id": "layout_direction",
      "label": "t:labels.layout_direction",
      "default": "group--vertical",
      "options": [
        { "value": "group--horizontal", "label": "t:options.direction.horizontal" },
        { "value": "group--vertical", "label": "t:options.direction.vertical" }
      ]
    },
    {
      "visible_if": "{{ block.settings.layout_direction == 'group--vertical' }}",
      "type": "select",
      "id": "alignment",
      "label": "t:labels.alignment",
      "default": "flex-start",
      "options": [
        { "value": "flex-start", "label": "t:options.alignment.left" },
        { "value": "center", "label": "t:options.alignment.center" },
        { "value": "flex-end", "label": "t:options.alignment.right" }
      ]
    },
    {
      "type": "range",
      "id": "padding",
      "label": "t:labels.padding",
      "default": 0,
      "min": 0,
      "max": 200,
      "step": 2,
      "unit": "px"
    }
  ],
  "presets": [
    {
      "name": "t:general.column",
      "category": "t:general.layout",
      "settings": {
        "layout_direction": "group--vertical",
        "alignment": "flex-start",
        "padding": 0
      }
    },
    {
      "name": "t:general.row",
      "category": "t:general.layout",
      "settings": {
        "layout_direction": "group--horizontal",
        "padding": 0
      }
    }
  ]
}
{% endschema %}

Key patterns:

• "blocks": [{ "type": "@theme" }] allows any theme block as child
• {% content_for 'blocks' %} renders the nested blocks
• visible_if conditionally shows the alignment setting only when vertical layout is selected
• Multiple presets (Column and Row) with different default settings
• range setting with required min, max, default, and optional step/unit

Section Example

Sections live in sections/, always have {% schema %}, and use {% content_for 'blocks' %} to render their blocks.

File: `sections/custom-section.liquid`

<div class="example-section full-width">
  {% if section.settings.background_image %}
    <div class="example-section__background">
      {{ section.settings.background_image | image_url: width: 2000 | image_tag }}
    </div>
  {% endif %}

  <div class="custom-section__content">
    {% content_for 'blocks' %}
  </div>
</div>

{% stylesheet %}
  .example-section {
    position: relative;
    overflow: hidden;
    width: 100%;
  }
  .example-section__background {
    position: absolute;
    width: 100%;
    height: 100%;
    z-index: -1;
    overflow: hidden;
  }
  .example-section__background img {
    position: absolute;
    width: 100%;
    height: auto;
    top: 50%;
    left: 50%;
    transform: translate(-50%, -50%);
  }
  .example-section__content {
    display: grid;
    grid-template-columns: var(--content-grid);
  }

  .example-section__content > * {
    grid-column: 2;
  }
{% endstylesheet %}

{% schema %}
{
  "name": "t:general.custom_section",
  "blocks": [{ "type": "@theme" }],
  "settings": [
    {
      "type": "image_picker",
      "id": "background_image",
      "label": "t:labels.background"
    }
  ],
  "presets": [
    {
      "name": "t:general.custom_section"
    }
  ]
}
{% endschema %}

Key patterns:

• Sections use section.settings.* (not block.settings.*)
• No {% doc %} tag needed for sections (they are not rendered via {% render %})
• image_picker setting accessed with | image_url: width: N | image_tag filter chain
• {% content_for 'blocks' %} renders merchant-configurable blocks
• Presets are required for sections to appear in "Add section" menu
• "blocks": [{ "type": "@theme" }] makes the section accept any theme block

Liquid Filters — Commerce

30 filters across 8 categories.

Cart

item_count_for_variant

• Syntax: {{ cart | item_count_for_variant: {variant_id} }}
• Returns: number
• Returns the total item count for a specified variant in the cart object.

{{ cart | item_count_for_variant: 39888235757633 }}

line_items_for

• Syntax: {{ cart | line_items_for: object }}
• Returns: array
• Returns the subset of cart line items that include a specified product or variant.

{% assign product = all_products['bloodroot-whole'] %}
{% assign line_items = cart | line_items_for: product %}

Total cart quantity for product: {{ line_items | sum: 'quantity' }}

Collection

link_to_type

• Syntax: {{ string | link_to_type }}
• Returns: string
• Generates an HTML <a> tag with an href attribute linking to a collection page that lists all products of the given

product type.

{{ 'Health' | link_to_type }}

link_to_vendor

• Syntax: {{ string | link_to_vendor }}
• Returns: string
• Generates an HTML <a> tag with an href attribute linking to a collection page that lists all products of a given

product vendor.

{{ "Polina's Potent Potions" | link_to_vendor }}

sort_by

• Syntax: {{ string | sort_by: string }}
• Returns: string
• Generates a collection URL with the provided sort_by parameter appended.

This filter must be applied to the object property collection.url.

{{ collection.url | sort_by: 'best-selling' }}

url_for_type

• Syntax: {{ string | url_for_type }}
• Returns: string
• Generates a URL for a collection page that lists all products of the given product type.

{{ 'health' | url_for_type }}

url_for_vendor

• Syntax: {{ string | url_for_vendor }}
• Returns: string
• Generates a URL for a collection page that lists all products from the given product vendor.

{{ "Polina's Potent Potions" | url_for_vendor }}

within

• Syntax: {{ string | within: collection }}
• Returns: string
• Generates a product URL within the context of the provided collection.

{%- assign collection_product = collection.products.first -%}

{{ collection_product.url | within: collection }}

highlight_active_tag

• Syntax: {{ string | highlight_active_tag }}
• Returns: string
• Wraps a given tag within the collection object in an HTML <span> tag, with a class attribute of active, if the tag is currently active. Only

applies to collection tags.

{% for tag in collection.all_tags %}
  {{- tag | highlight_active_tag | link_to_tag: tag }}
{% endfor %}

Customer

customer_login_link

• Syntax: {{ string | customer_login_link }}
• Returns: string
• Generates an HTML link to the customer login page.

{{ 'Log in' | customer_login_link }}

customer_logout_link

• Syntax: {{ string | customer_logout_link }}
• Returns: string
• Generates an HTML link to log the customer out of their account and redirect to the homepage.

{{ 'Log out' | customer_logout_link }}

customer_register_link

• Syntax: {{ string | customer_register_link }}
• Returns: string
• Generates an HTML link to the customer registration page.

{{ 'Create an account' | customer_register_link }}

avatar

• Syntax: {{ customer | avatar }}
• Returns: string
• Generates HTML to render a customer's avatar, if available.

login_button

• Syntax: {{ shop | login_button }}
• Returns: string
• Generates an HTML Button that enables a customer to either sign in to the storefront using their Shop account or follow the shop in the Shop App.

Localization

currency_selector (deprecated)

• Syntax: {{ form | currency_selector }}
• Returns: string
• Generates an HTML <select> element with an option for each currency available on the store.

{% form 'currency' %}
  {{ form | currency_selector }}
{% endform %}

translate

• Syntax: {{ string | t }}
• Returns: string
• Returns a string of translated text for a given translation key from a locale file.

format_address

• Syntax: {{ address | format_address }}
• Returns: string
• Generates an HTML address display, with each address component ordered according to the address's locale.

{{ shop.address | format_address }}

Metafield

metafield_tag

• Syntax: {{ metafield | metafield_tag }}
• Returns: string
• Generates an HTML element to host the data from a metafield object.

The type of element that's generated differs depending on the type of metafield.

<!-- boolean -->
{{ product.metafields.information.seasonal | metafield_tag }}

<!-- collection_reference -->
{{ product.metafields.information.related_collection | metafield_tag }}

<!-- color -->
{{ product.metafields.details.potion_color | metafield_tag }}

<!-- date -->
{{ product.metafields.information.expiry | metafield_tag }}

<!-- date_time -->
{{ product.metafields.information.brew_date | metafield_tag }}

<!-- json -->
{{ product.metafields.information.burn_temperature | metafield_tag }}

<!-- money -->
{{ product.metafields.details.price_per_ml | metafield_tag }}

<!-- multi_line_text_field -->
{{ product.metafields.information.shipping | metafield_tag }}

<!-- number_decimal -->
{{ product.metafields.information.salinity | metafield_tag }}

<!-- number_integer -->
{{ product.metafields.information.doses_per_day | metafield_tag }}

<!-- page_reference -->
{{ product.metafields.information.dosage | metafield_tag }}

<!-- product_reference -->
{{ product.metafields.information.related_product | metafield_tag }}

<!-- rating -->
{{ product.metafields.details.rating | metafield_tag }}

<!-- single_line_text_field -->
{{ product.metafields.information.directions | metafield_tag }}

<!-- url -->
{{ product.metafields.information.health | metafield_tag }}

<!-- variant_reference -->
{{ product.metafields.information.best_seller | metafield_tag }}

<!-- rich_text_field -->
{{ product.metafields.information.rich_description | metafield_tag }}

metafield_text

• Syntax: {{ metafield | metafield_text }}
• Returns: string
• Generates a text version of the data from a metafield object.

{{ product.metafields.information.dosage | metafield_text }}

Money

money

• Syntax: {{ number | money }}
• Returns: string
• Formats a given price based on the store's HTML without currency setting.

{{ product.price | money }}

money_with_currency

• Syntax: {{ number | money_with_currency }}
• Returns: string
• Formats a given price based on the store's HTML with currency setting.

{{ product.price | money_with_currency }}

money_without_currency

• Syntax: {{ number | money_without_currency }}
• Returns: string
• Formats a given price based on the store's HTML without currency setting, without the currency symbol.

{{ product.price | money_without_currency }}

money_without_trailing_zeros

• Syntax: {{ number | money_without_trailing_zeros }}
• Returns: string
• Formats a given price based on the store's HTML without currency setting, excluding the decimal separator

(either . or ,) and trailing zeros.

If the price has a non-zero decimal value, then the output is the same as the money filter.

{{ product.price | money_without_trailing_zeros }}

Payment

payment_button

• Syntax: {{ form | payment_button }}
• Returns: string
• Generates an HTML container to host accelerated checkout buttons

for a product. The payment_button filter must be used on the form object within a product form.

{% form 'product', product %}
  {{ form | payment_button }}
{% endform %}

payment_terms

• Syntax: {{ form | payment_terms }}
• Returns: string
• Generates the HTML for the Shop Pay Installments banner.

payment_type_img_url

• Syntax: {{ string | payment_type_img_url }}
• Returns: string
• Returns the URL for an SVG image of a given payment type.

{% for type in shop.enabled_payment_types %}
<img src="{{ type | payment_type_img_url }}" width="50" height="50" />
{% endfor %}

payment_type_svg_tag

• Syntax: {{ string | payment_type_svg_tag }}
• Returns: string
• Generates an HTML <svg> tag for a given payment type.

{% for type in shop.enabled_payment_types -%}
  {{ type | payment_type_svg_tag }}
{% endfor %}

Tag

link_to_add_tag

• Syntax: {{ string | link_to_add_tag }}
• Returns: string
• Generates an HTML <a> tag with an href attribute linking to the current blog or collection, filtered to show

only articles or products that have a given tag, as well as any currently active tags.

{% for tag in collection.all_tags %}
  {%- if current_tags contains tag -%}
    {{ tag }}
  {%- else -%}
    {{ tag | link_to_add_tag: tag }}
  {%- endif -%}
{% endfor %}

link_to_remove_tag

• Syntax: {{ string | link_to_remove_tag }}
• Returns: string
• Generates an HTML <a> tag with an href attribute linking to the current blog or collection, filtered to show

only articles or products that have any currently active tags, except the provided tag.

{% for tag in collection.all_tags %}
  {%- if current_tags contains tag -%}
    {{ tag | link_to_remove_tag: tag }}
  {%- else -%}
    {{ tag | link_to_add_tag: tag }}
  {%- endif -%}
{% endfor %}

link_to_tag

• Syntax: {{ string | link_to_tag }}
• Returns: string
• Generates an HTML <a> tag with an href attribute linking to the current blog or collection, filtered to show

only articles or products that have a given tag.

{% for tag in collection.all_tags %}
  {{- tag | link_to_tag: tag }}
{% endfor %}

Liquid Filters — Html media

45 filters across 5 categories.

Color

brightness_difference

• Syntax: {{ string | brightness_difference: string }}
• Returns: number
• Calculates the perceived brightness difference between two colors.

{{ '#E800B0' | brightness_difference: '#FECEE9' }}

color_brightness

• Syntax: {{ string | color_brightness }}
• Returns: number
• Calculates the perceived brightness of a given color.

{{ '#EA5AB9' | color_brightness }}

color_contrast

• Syntax: {{ string | color_contrast: string }}
• Returns: number
• Calculates the contrast ratio between two colors and returns the ratio's numerator. The ratio's denominator, which isn't

returned, is always 1. For example, with a contrast ratio of 3.5:1, this filter returns 3.5.

{{ '#E800B0' | color_contrast: '#D9D8FF' }}

color_darken

• Syntax: {{ string | color_darken: number }}
• Returns: string
• Darkens a given color by a specific percentage. The percentage must be between 0 and 100.

{{ '#EA5AB9' | color_darken: 30 }}

color_desaturate

• Syntax: {{ string | color_desaturate: number }}
• Returns: string
• Desaturates a given color by a specific percentage. The percentage must be between 0 and 100.

{{ '#EA5AB9' | color_desaturate: 30 }}

color_difference

• Syntax: {{ string | color_difference: string }}
• Returns: number
• Calculates the color difference between two colors.

{{ '#720955' | color_difference: '#FFF3F9' }}

color_extract

• Syntax: {{ string | color_extract: string }}
• Returns: number
• Extracts a specific color component from a given color.

{{ '#EA5AB9' | color_extract: 'red' }}

color_lighten

• Syntax: {{ string | color_lighten: number }}
• Returns: string
• Lightens a given color by a specific percentage. The percentage must be between 0 and 100.

{{ '#EA5AB9' | color_lighten: 30 }}

color_mix

• Syntax: {{ string | color_mix: string, number }}
• Returns: string
• Blends two colors together by a specific percentage factor. The percentage must be between 0 and 100.

{{ '#E800B0' | color_mix: '#00936F', 50 }}

color_modify

• Syntax: {{ string | color_modify: string, number }}
• Returns: string
• Modifies a specific color component of a given color by a specific amount.

{{ '#EA5AB9' | color_modify: 'red', 255 }}

color_saturate

• Syntax: {{ string | color_saturate: number }}
• Returns: string
• Saturates a given color by a specific percentage. The percentage must be between 0 and 100.

{{ '#EA5AB9' | color_saturate: 30 }}

color_to_hex

• Syntax: {{ string | color_to_hex }}
• Returns: string
• Converts a CSS color string to hexadecimal format (hex6).

{{ 'rgb(234, 90, 185)' | color_to_hex }}

color_to_hsl

• Syntax: {{ string | color_to_hsl }}
• Returns: string
• Converts a CSS color string to HSL format.

{{ '#EA5AB9' | color_to_hsl }}

color_to_oklch

• Syntax: {{ string | color_to_oklch }}
• Returns: string
• Converts a CSS color string to OKLCH format.

{{ '#EA5AB9' | color_to_oklch }}

color_to_rgb

• Syntax: {{ string | color_to_rgb }}
• Returns: string
• Converts a CSS color string to RGB format.

{{ '#EA5AB9' | color_to_rgb }}

hex_to_rgba (deprecated)

• Syntax: {{ string | hex_to_rgba }}
• Returns: string
• Converts a CSS color string from hexadecimal format to RGBA format. Shorthand hexadecimal formatting (hex3) is also accepted.

{{ '#EA5AB9' | hex_to_rgba }}

Font

font_face

• Syntax: {{ font | font_face }}
• Returns: string
• Generates a CSS @font_face declaration to load the provided font.

{{ settings.type_header_font | font_face }}

font_modify

• Syntax: {{ font | font_modify: string, string }}
• Returns: font
• Modifies a specific property of a given font.

{%- assign bold_font = settings.type_body_font | font_modify: 'weight', 'bold' -%}

h2 {
  font-weight: {{ bold_font.weight }};
}

font_url

• Syntax: {{ font | font_url }}
• Returns: string
• Returns the CDN URL for the provided font in woff2 format.

{{ settings.type_header_font | font_url }}

Hosted file

asset_img_url

• Syntax: {{ string | asset_img_url }}
• Returns: string
• Returns the CDN URL for an image in the

assets directory of a theme.

{{ 'red-and-black-bramble-berries.jpg' | asset_img_url }}

asset_url

• Syntax: {{ string | asset_url }}
• Returns: string
• Returns the CDN URL for a file in the

assets directory of a theme.

{{ 'cart.js' | asset_url }}

file_img_url

• Syntax: {{ string | file_img_url }}
• Returns: string
• Returns the CDN URL for an image from the

Files page of the Shopify admin.

{{ 'potions-header.png' | file_img_url }}

file_url

• Syntax: {{ string | file_url }}
• Returns: string
• Returns the CDN URL for a file from the

Files page of the Shopify admin.

{{ 'disclaimer.pdf' | file_url }}

global_asset_url

• Syntax: {{ string | global_asset_url }}
• Returns: string
• Returns the CDN URL for a global asset.

{{ 'lightbox.js' | global_asset_url | script_tag }}

{{ 'lightbox.css' | global_asset_url | stylesheet_tag }}

shopify_asset_url

• Syntax: {{ string | shopify_asset_url }}
• Returns: string
• Returns the CDN URL for a globally accessible Shopify asset.

{{ 'option_selection.js' | shopify_asset_url }}

Html

time_tag

• Syntax: {{ string | time_tag: string }}
• Returns: string
• Converts a timestamp into an HTML <time> tag.

{{ article.created_at | time_tag: '%B %d, %Y' }}

inline_asset_content

• Syntax: {{ asset_name | inline_asset_content }}
• Returns: string
• Outputs the content of an asset inline in the template. The asset must be either a SVG, JS, or CSS file.

{{ 'icon.svg' | inline_asset_content }}

highlight

• Syntax: {{ string | highlight: string }}
• Returns: string
• Wraps all instances of a specific string, within a given string, with an HTML <strong> tag with a class attribute

of highlight.

{% for item in search.results %}
  {% if item.object_type == 'product' %}
    {{ item.description | highlight: search.terms }}
  {% else %}
    {{ item.content | highlight: search.terms }}
  {% endif %}
{% endfor %}

link_to

• Syntax: {{ string | link_to: string }}
• Returns: string
• Generates an HTML <a> tag.

{{ 'Shopify' | link_to: 'https://www.shopify.com' }}

placeholder_svg_tag

• Syntax: {{ string | placeholder_svg_tag }}
• Returns: string
• Generates an HTML <svg> tag for a given placeholder name.

{{ 'collection-1' | placeholder_svg_tag }}

preload_tag

• Syntax: {{ string | preload_tag: as: string }}
• Returns: string
• Generates an HTML <link> tag with a rel attribute of preload to prioritize loading a given Shopify-hosted asset.

The asset URL is also added to the Link header with a rel attribute of preload.

{{ 'cart.js' | asset_url | preload_tag: as: 'script' }}

script_tag

• Syntax: {{ string | script_tag }}
• Returns: string
• Generates an HTML <script> tag for a given resource URL. The tag has a type attribute of text/javascript.

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

stylesheet_tag

• Syntax: {{ string | stylesheet_tag }}
• Returns: string
• Generates an HTML <link> tag for a given resource URL. The tag has the following parameters:

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

Media

external_video_tag

• Syntax: {{ variable | external_video_tag }}
• Returns: string
• Generates an HTML <iframe> tag containing the player for a given external video. The input for the external_video_tag

filter can be either a media object or external_video_url.

{% for media in product.media %}
  {% if media.media_type == 'external_video' %}
    {% if media.host == 'youtube' %}
      {{ media | external_video_url: color: 'white' | external_video_tag }}
    {% elsif media.host == 'vimeo' %}
      {{ media | external_video_url: loop: '1', muted: '1' | external_video_tag }}
    {% endif %}
  {% endif %}
{% endfor %}

external_video_url

• Syntax: {{ media | external_video_url: attribute: string }}
• Returns: string
• Returns the URL for a given external video. Use this filter to specify parameters for the external video player generated

by the external_video_tag filter.

{% for media in product.media %}
  {% if media.media_type == 'external_video' %}
    {% if media.host == 'youtube' %}
      {{ media | external_video_url: color: 'white' | external_video_tag }}
    {% elsif media.host == 'vimeo' %}
      {{ media | external_video_url: loop: '1', muted: '1' | external_video_tag }}
    {% endif %}
  {% endif %}
{% endfor %}

image_tag

• Syntax: {{ string | image_tag }}
• Returns: string
• Generates an HTML <img> tag for a given image_url.

{{ product | image_url: width: 200 | image_tag }}

media_tag

• Syntax: {{ media | media_tag }}
• Returns: string
• Generates an appropriate HTML tag for a given media object.

{% for media in product.media %}
  {{- media | media_tag }}
{% endfor %}

model_viewer_tag

• Syntax: {{ media | model_viewer_tag }}
• Returns: string
• Generates a Google model viewer component for a given 3D model.

{% for media in product.media %}
  {% if media.media_type == 'model' %}
    {{ media | model_viewer_tag }}
  {% endif %}
{% endfor %}

video_tag

• Syntax: {{ media | video_tag }}
• Returns: string
• Generates an HTML <video> tag for a given video.

{% for media in product.media %}
  {% if media.media_type == 'video' %}
    {{ media | video_tag }}
  {% endif %}
{% endfor %}

article_img_url (deprecated)

• Syntax: {{ variable | article_img_url }}
• Returns: string
• Returns the CDN URL for an article's image.

{{ article.image | article_img_url }}

collection_img_url (deprecated)

• Syntax: {{ variable | collection_img_url }}
• Returns: string
• Returns the CDN URL for a collection's image.

{{ collection.image | collection_img_url }}

image_url

• Syntax: {{ variable | image_url: width: number, height: number }}
• Returns: string
• Returns the CDN URL for an image.

{{ product | image_url: width: 450 }}

img_tag (deprecated)

• Syntax: {{ string | img_tag }}
• Returns: string
• Generates an HTML <img> tag for a given image URL.

{{ product | img_tag }}

img_url (deprecated)

• Syntax: {{ variable | img_url }}
• Returns: string
• Returns the CDN URL for an image.

{{ product | img_url }}

product_img_url (deprecated)

• Syntax: {{ variable | product_img_url }}
• Returns: string
• Returns the CDN URL for a product image.

{{ product.featured_image | product_img_url }}

Liquid Filters — Language

77 filters across 6 categories.

Array

compact

• Syntax: {{ array | compact }}
• Returns: array
• Removes any nil items from an array.

{%- assign original_prices = collection.products | map: 'compare_at_price' -%}

Original prices:

{% for price in original_prices -%}
  - {{ price }}
{%- endfor %}

{%- assign compacted_original_prices = original_prices | compact -%}

Original prices - compacted:

{% for price in compacted_original_prices -%}
  - {{ price }}
{%- endfor %}

concat

• Syntax: {{ array | concat: array }}
• Returns: array
• Concatenates (combines) two arrays.

{%- assign types_and_vendors = collection.all_types | concat: collection.all_vendors -%}

Types and vendors:

{% for item in types_and_vendors -%}
  {%- if item != blank -%}
    - {{ item }}
  {%- endif -%}
{%- endfor %}

find

• Syntax: {{ array | find: string, string }}
• Returns: untyped
• Returns the first item in an array with a specific property value.

{% assign product = collection.products | find: 'vendor', "Polina's Potent Potions" %}

{{ product.title }}

find_index

• Syntax: {{ array | find_index: string, string }}
• Returns: number
• Returns the index of the first item in an array with a specific property value.

{% assign index = collection.products | find_index: 'vendor', "Polina's Potent Potions" %}

{{ index }}

first

• Syntax: {{ array | first }}
• Returns: untyped
• Returns the first item in an array.

{%- assign first_product = collection.products | first -%}

{{ first_product.title }}

has

• Syntax: {{ array | has: string, string }}
• Returns: boolean
• Tests if any item in an array has a specific property value.

{% assign has_potent_potions = collection.products | has: 'vendor', "Polina's Potent Potions" %}

{{ has_potent_potions }}

join

• Syntax: {{ array | join }}
• Returns: string
• Combines all of the items in an array into a single string, separated by a space.

{{ collection.all_tags | join }}

last

• Syntax: {{ array | last }}
• Returns: untyped
• Returns the last item in an array.

{%- assign last_product = collection.products | last -%}

{{ last_product.title }}

map

• Syntax: {{ array | map: string }}
• Returns: array
• Creates an array of values from a specific property of the items in an array.

{%- assign product_titles = collection.products | map: 'title' -%}

{{ product_titles | join: ', ' }}

reject

• Syntax: {{ array | reject: string, string }}
• Returns: array
• Filters an array to exclude items with a specific property value.

{% assign polina_products = collection.products | reject: 'vendor', "Polina's Potent Potions" %}

Products from other vendors than Polina's Potent Potions:

{% for product in polina_products -%}
  - {{ product.title }}
{%- endfor %}

reverse

• Syntax: {{ array | reverse }}
• Returns: array
• Reverses the order of the items in an array.

Original order:
{{ collection.products | map: 'title' | join: ', ' }}

Reverse order:
{{ collection.products | reverse | map: 'title' | join: ', ' }}

size

• Syntax: {{ variable | size }}
• Returns: number
• Returns the size of a string or array.

{{ collection.title | size }}
{{ collection.products | size }}

sort

• Syntax: {{ array | sort }}
• Returns: array
• Sorts the items in an array in case-sensitive alphabetical, or numerical, order.

{% assign tags = collection.all_tags | sort %}

{% for tag in tags -%}
  {{ tag }}
{%- endfor %}

sort_natural

• Syntax: {{ array | sort_natural }}
• Returns: array
• Sorts the items in an array in case-insensitive alphabetical order.

{% assign tags = collection.all_tags | sort_natural %}

{% for tag in tags -%}
  {{ tag }}
{%- endfor %}

sum

• Syntax: {{ array | sum }}
• Returns: number
• Returns the sum of all elements in an array.

{% assign fibonacci = '0, 1, 1, 2, 3, 5' | split: ', ' %}

{{ fibonacci | sum }}

uniq

• Syntax: {{ array | uniq }}
• Returns: array
• Removes any duplicate items in an array.

{% assign potion_array = 'invisibility, health, love, health, invisibility' | split: ', ' %}

{{ potion_array | uniq | join: ', ' }}

where

• Syntax: {{ array | where: string, string }}
• Returns: array
• Filters an array to include only items with a specific property value.

{% assign polina_products = collection.products | where: 'vendor', "Polina's Potent Potions" %}

Products from Polina's Potent Potions:

{% for product in polina_products -%}
  - {{ product.title }}
{%- endfor %}

Date

date

• Syntax: {{ date | date: string }}
• Returns: string
• Formats a date according to a specified format string.

Default

default_errors

• Syntax: {{ string | default_errors }}
• Returns: string
• Generates default error messages for each possible value of form.errors.

default

• Syntax: {{ variable | default: variable }}
• Returns: untyped
• Sets a default value for any variable whose value is one of the following:

• empty
• false
• nil

{{ product.selected_variant.url | default: product.url }}

default_pagination

• Syntax: {{ paginate | default_pagination }}
• Returns: string
• Generates HTML for a set of links for paginated results. Must be applied to the paginate object.

{% paginate collection.products by 2 %}
  {% for product in collection.products %}
    {{- product.title }}
  {% endfor %}

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

Format

date

• Syntax: {{ string | date: string }}
• Returns: string
• Converts a timestamp into another date format.

{{ article.created_at | date: '%B %d, %Y' }}

json

• Syntax: {{ variable | json }}
• Returns: string
• Converts a string, or object, into JSON format.

{{ product | json }}

structured_data

• Syntax: {{ variable | structured_data }}
• Returns: string
• Converts an object into a schema.org structured data format.

<script type="application/ld+json">
  {{ product | structured_data }}
</script>

unit_price_with_measurement

• Syntax: {{ number | unit_price_with_measurement: unit_price_measurement }}
• Returns: string
• Formats a given unit price and measurement based on the store's HTML without currency setting.

{%- assign variant = product.variants.first -%}

{{ variant.unit_price | unit_price_with_measurement: variant.unit_price_measurement }}

weight_with_unit

• Syntax: {{ number | weight_with_unit }}
• Returns: string
• Generates a formatted weight for a variant object. The weight unit is

set in the general settings in the Shopify admin.

{%- assign variant = product.variants.first -%}

{{ variant.weight | weight_with_unit }}

Math

abs

• Syntax: {{ number | abs }}
• Returns: number
• Returns the absolute value of a number.

{{ -3 | abs }}

at_least

• Syntax: {{ number | at_least }}
• Returns: number
• Limits a number to a minimum value.

{{ 4 | at_least: 5 }}
{{ 4 | at_least: 3 }}

at_most

• Syntax: {{ number | at_most }}
• Returns: number
• Limits a number to a maximum value.

{{ 6 | at_most: 5 }}
{{ 4 | at_most: 5 }}

ceil

• Syntax: {{ number | ceil }}
• Returns: number
• Rounds a number up to the nearest integer.

{{ 1.2 | ceil }}

divided_by

• Syntax: {{ number | divided_by: number }}
• Returns: number
• Divides a number by a given number. The divided_by filter produces a result of the same type as the divisor. This means if you divide by an integer, the result will be an integer, and if you divide by a float, the result will be a float.

{{ 4 | divided_by: 2 }}

# divisor is an integer
{{ 20 | divided_by: 7 }}

# divisor is a float 
{{ 20 | divided_by: 7.0 }}

floor

• Syntax: {{ number | floor }}
• Returns: number
• Rounds a number down to the nearest integer.

{{ 1.2 | floor }}

minus

• Syntax: {{ number | minus: number }}
• Returns: number
• Subtracts a given number from another number.

{{ 4 | minus: 2 }}

modulo

• Syntax: {{ number | modulo: number }}
• Returns: number
• Returns the remainder of dividing a number by a given number.

{{ 12 | modulo: 5 }}

plus

• Syntax: {{ number | plus: number }}
• Returns: number
• Adds two numbers.

{{ 2 | plus: 2 }}

round

• Syntax: {{ number | round }}
• Returns: number
• Rounds a number to the nearest integer.

{{ 2.7 | round }}
{{ 1.3 | round }}

times

• Syntax: {{ number | times: number }}
• Returns: number
• Multiplies a number by a given number.

{{ 2 | times: 2 }}

String

blake3

• Syntax: {{ string | blake3 }}
• Returns: string
• Converts a string into a Blake3 hash.

{{ '' | blake3 }}

hmac_sha1

• Syntax: {{ string | hmac_sha1: string }}
• Returns: string
• Converts a string into an SHA-1 hash using a hash message authentication code (HMAC).

{%- assign secret_potion = 'Polyjuice' | hmac_sha1: 'Polina' -%}

My secret potion: {{ secret_potion }}

hmac_sha256

• Syntax: {{ string | hmac_sha256: string }}
• Returns: string
• Converts a string into an SHA-256 hash using a hash message authentication code (HMAC).

{%- assign secret_potion = 'Polyjuice' | hmac_sha256: 'Polina' -%}

My secret potion: {{ secret_potion }}

md5

• Syntax: {{ string | md5 }}
• Returns: string
• Converts a string into an MD5 hash. MD5 is not considered safe anymore. Please use 'blake3' instead for better security and performance.

{{ '' | md5 }}

sha1

• Syntax: {{ string | sha1: string }}
• Returns: string
• Converts a string into an SHA-1 hash. SHA-1 is not considered safe anymore. Please use 'blake3' instead for better security and performance.

{%- assign secret_potion = 'Polyjuice' | sha1 -%}

My secret potion: {{ secret_potion }}

sha256

• Syntax: {{ string | sha256: string }}
• Returns: string
• Converts a string into an SHA-256 hash. Please use 'blake3' instead for better security and performance.

{%- assign secret_potion = 'Polyjuice' | sha256 -%}

My secret potion: {{ secret_potion }}

append

• Syntax: {{ string | append: string }}
• Returns: string
• Adds a given string to the end of a string.

{%-  assign path = product.url -%}

{{ request.origin | append: path }}

base64_decode

• Syntax: {{ string | base64_decode }}
• Returns: string
• Decodes a string in Base64 format.

{{ 'b25lIHR3byB0aHJlZQ==' | base64_decode }}

base64_encode

• Syntax: {{ string | base64_encode }}
• Returns: string
• Encodes a string to Base64 format.

{{ 'one two three' | base64_encode }}

base64_url_safe_decode

• Syntax: {{ string | base64_url_safe_decode }}
• Returns: string
• Decodes a string in URL-safe Base64 format.

{{ 'b25lIHR3byB0aHJlZQ==' | base64_url_safe_decode }}

base64_url_safe_encode

• Syntax: {{ string | base64_url_safe_encode }}
• Returns: string
• Encodes a string to URL-safe Base64 format.

{{ 'one two three' | base64_url_safe_encode }}

capitalize

• Syntax: {{ string | capitalize }}
• Returns: string
• Capitalizes the first word in a string and downcases the remaining characters.

{{ 'this sentence should start with a capitalized word.' | capitalize }}

downcase

• Syntax: {{ string | downcase }}
• Returns: string
• Converts a string to all lowercase characters.

{{ product.title | downcase }}

escape

• Syntax: {{ string | escape }}
• Returns: string
• Escapes special characters in HTML, such as <>, ', and &, and converts characters into escape sequences. The filter doesn't effect characters within the string that don’t have a corresponding escape sequence.".

{{ '<p>Text to be escaped.</p>' | escape }}

escape_once

• Syntax: {{ string | escape_once }}
• Returns: string
• Escapes a string without changing characters that have already been escaped.

# applying the escape filter to already escaped text escapes characters in HTML entities:

{{ "<p>Text to be escaped.</p>" | escape }}

# applying the escape_once filter to already escaped text skips characters in HTML entities:

{{ "<p>Text to be escaped.</p>" | escape_once }}

# use escape_once to escape strings where a combination of HTML entities and non-escaped characters might be present:

{{ "<p>Text to be escaped.</p> & some additional text" | escape_once }}

lstrip

• Syntax: {{ string | lstrip }}
• Returns: string
• Strips all whitespace from the left of a string.

{%- assign text = '  Some potions create whitespace.      ' -%}

"{{ text }}"
"{{ text | lstrip }}"

newline_to_br

• Syntax: {{ string | newline_to_br }}
• Returns: string
• Converts newlines (\n) in a string to HTML line breaks (<br>).

{{ product.description | newline_to_br }}

prepend

• Syntax: {{ string | prepend: string }}
• Returns: string
• Adds a given string to the beginning of a string.

{%- assign origin = request.origin -%}

{{ product.url | prepend: origin }}

remove

• Syntax: {{ string | remove: string }}
• Returns: string
• Removes any instance of a substring inside a string.

{{ "I can't do it!" | remove: "'t" }}

remove_first

• Syntax: {{ string | remove_first: string }}
• Returns: string
• Removes the first instance of a substring inside a string.

{{ "I hate it when I accidentally spill my duplication potion accidentally!" | remove_first: ' accidentally' }}

remove_last

• Syntax: {{ string | remove_last: string }}
• Returns: string
• Removes the last instance of a substring inside a string.

{{ "I hate it when I accidentally spill my duplication potion accidentally!" | remove_last: ' accidentally' }}

replace

• Syntax: {{ string | replace: string, string }}
• Returns: string
• Replaces any instance of a substring inside a string with a given string.

{{ product.handle | replace: '-', ' ' }}

replace_first

• Syntax: {{ string | replace_first: string, string }}
• Returns: string
• Replaces the first instance of a substring inside a string with a given string.

{{ product.handle | replace_first: '-', ' ' }}

replace_last

• Syntax: {{ string | replace_last: string, string }}
• Returns: string
• Replaces the last instance of a substring inside a string with a given string.

{{ product.handle | replace_last: '-', ' ' }}

rstrip

• Syntax: {{ string | rstrip }}
• Returns: string
• Strips all whitespace from the right of a string.

{%- assign text = '  Some potions create whitespace.      ' -%}

"{{ text }}"
"{{ text | rstrip }}"

slice

• Syntax: {{ string | slice }}
• Returns: string
• Returns a substring or series of array items, starting at a given 0-based index.

{{ collection.title | slice: 0 }}
{{ collection.title | slice: 0, 5 }}

{{ collection.all_tags | slice: 1, 2 | join: ', ' }}

split

• Syntax: {{ string | split: string }}
• Returns: array
• Splits a string into an array of substrings based on a given separator.

{%- assign title_words = product.handle | split: '-' -%}

{% for word in title_words -%}
  {{ word }}
{%- endfor %}

strip

• Syntax: {{ string | strip }}
• Returns: string
• Strips all whitespace from the left and right of a string.

{%- assign text = '  Some potions create whitespace.      ' -%}

"{{ text }}"
"{{ text | strip }}"

strip_html

• Syntax: {{ string | strip_html }}
• Returns: string
• Strips all HTML tags from a string.

<!-- With HTML -->
{{ product.description }}

<!-- HTML stripped -->
{{ product.description | strip_html }}

strip_newlines

• Syntax: {{ string | strip_newlines }}
• Returns: string
• Strips all newline characters (line breaks) from a string.

<!-- With newlines -->
{{ product.description }}

<!-- Newlines stripped -->
{{ product.description | strip_newlines }}

truncate

• Syntax: {{ string | truncate: number }}
• Returns: string
• Truncates a string down to a given number of characters.

{{ article.title | truncate: 15 }}

truncatewords

• Syntax: {{ string | truncatewords: number }}
• Returns: string
• Truncates a string down to a given number of words.

{{ article.content | strip_html | truncatewords: 15 }}

upcase

• Syntax: {{ string | upcase }}
• Returns: string
• Converts a string to all uppercase characters.

{{ product.title | upcase }}

url_decode

• Syntax: {{ string | url_decode }}
• Returns: string
• Decodes any percent-encoded characters

in a string.

{{ 'test%40test.com' | url_decode }}

url_encode

• Syntax: {{ string | url_encode }}
• Returns: string
• Converts any URL-unsafe characters in a string to the

percent-encoded equivalent.

{{ 'test@test.com' | url_encode }}

camelize

• Syntax: {{ string | camelize }}
• Returns: string
• Converts a string to CamelCase.

{{ 'variable-name' | camelize }}

handleize

• Syntax: {{ string | handleize }}
• Returns: string
• Converts a string into a handle.

{{ product.title | handleize }}
{{ product.title | handle }}

url_escape

• Syntax: {{ string | url_escape }}
• Returns: string
• Escapes any URL-unsafe characters in a string.

{{ '<p>Health & Love potions</p>' | url_escape }}

url_param_escape

• Syntax: {{ string | url_param_escape }}
• Returns: string
• Escapes any characters in a string that are unsafe for URL parameters.

{{ '<p>Health & Love potions</p>' | url_param_escape }}

pluralize

• Syntax: {{ number | pluralize: string, string }}
• Returns: string
• Outputs the singular or plural version of a string based on a given number.

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

Liquid Objects — Commerce

Core commerce objects with full property tables.

cart

A customer’s cart.

Access: Global

Properties:

line_item

A line in a cart, checkout, or order. Each line item represents a product variant.

Access: cart.line_items, checkout.line_items, order.line_items, parent_relationship.parent

Properties:

order

An order.

Access: checkout.order, customer.last_order, customer.orders

Properties:

product

A product in the store.

Access: all_products., collection.products, line_item.product, link.object, metafield.value, recommendations.products, search.results, variant.product

Properties:

variant

A product variant.

Access: line_item.variant, product.first_available_variant, product.selected_or_first_available_variant, product.variants, product.selected_variant, product_option_value.variant, remote_product.selected_or_first_available_variant, remote_product.selected_variant, remote_product.first_available_variant

Properties:

Liquid Objects — Content & Theme

Content and theme objects with full property tables.

article

An article, or blog post, in a blog.

Access: articles., blog.articles

Properties:

block

The content and settings of a section block.

Access: section.blocks

Properties:

blog

Information about a specific blog in the store.

Access: Templates: blog, article

Properties:

collection

A collection in a store.

Access: collections.

Properties:

customer

A customer of the store.

Access: Global

Properties:

form

Information about a form created by a form tag.

Properties:

image

An image, such as a product or collection image.

Access: article.image, blog.image, collection.image, generic_file.preview_image, line_item.image, media.preview_image, model.preview_image, product.featured_image, product.media, product.images, variant.image, video.preview_image, brand.favicon_url, brand.cover_image, brand.logo, brand.square_logo, collection.featured_image, external_video.preview_image, filter_value.image, image.preview_image, swatch.image, variant.featured_image, remote_product.featured_image, user.image, page_image.

Properties:

page

A page on a store.

Access: pages., metafield.value

Properties:

section

The properties and settings of a section.

Properties:

shop

Information about the store, such as the store address, the total number of products, and various settings.

Access: Global

Properties:

Liquid Objects — Tier 2

69 objects with property names listed.

address

An address, such as a customer address or order shipping address.

Access: checkout.billing_address, checkout.shipping_address, customer.addresses, customer.default_address, location.address, order.billing_address, order.shipping_address, shop.address

Properties: company, phone, first_name, last_name, name, url, summary, id, address1, address2, city, zip, country_code, province_code, country, street, province

brand

The brand assets for the store.

Access: remote_shop.brand, shop.brand

Properties: slogan, short_description, favicon_url, cover_image, logo, square_logo, colors, metafields

checkout

A customer's checkout.

Access: Templates: checkout

Properties: applied_gift_cards, attributes, billing_address, buyer_accepts_marketing, cart_level_discount_applications, currency, customer, discount_applications, discounts_amount, discounts_savings, email, gift_cards_amount, id, line_items, line_items_subtotal_price, name, note, order, order_id, order_name, order_number, requires_shipping, shipping_address, shipping_method, shipping_price, tax_lines, tax_price, total_price, transactions, item_count

closest

A drop that holds resources of different types that are the closest to the current context

Access: Global

Properties: product, collection, article, blog, page, metaobject

color

A color from a color setting.

Access: swatch.color

Properties: red, green, blue, rgb, rgba, oklch, oklcha, hue, saturation, lightness, alpha, chroma, color_space

comment

An article comment.

Access: article.comments

Properties: author, content, created_at, email, id, status, updated_at, url

company

A company that a customer is purchasing for.

Access: company_location.company, customer.current_company

Properties: id, name, external_id, available_locations, available_locations_count, metafields

company_address

The address of a company location.

Access: company_location.shipping_address

Properties: attention, id, address1, address2, first_name, last_name, city, zip, country_code, province_code, country, street, province

company_location

A location of the company that a customer is purchasing for.

Access: company.available_locations, customer.company_available_locations, customer.current_location

Properties: id, name, external_id, url_to_set_as_current, current?, company, shipping_address, tax_registration_id, metafields, store_credit_account

country

A country supported by the store's localization options.

Access: localization.available_countries, localization.country, address.country, company_address.country

Properties: name, iso_code, unit_system, currency, market, popular?, continent, available_languages

currency

Information about a currency, like the ISO code and symbol.

Access: cart.currency, country.currency, shop.enabled_currencies, money.currency, shop.money_format, shop.money_with_currency_format

Properties: iso_code, symbol, name

discount (deprecated)

A discount applied to a cart, line item, or order.

Access: cart.discounts, line_item.discounts, order.discounts, checkout.discount

Properties: amount, total_amount, code, title, type, savings, total_savings

discount_application

Information about the intent of a discount.

Access: cart.discount_applications, order.discount_applications, discount_allocation.discount_application

Properties: total_allocated_amount, title, value, target_selection, type, value_type, target_type

external_video

Information about an external video from YouTube or Vimeo.

Access: product.media

Properties: external_id, aspect_ratio, host, alt, id, media_type, position, preview_image

filter

A storefront filter.

Access: collection.filters, search.filters

Properties: param_name, label, operator, type, active_values, inactive_values, values, false_value, true_value, max_value, min_value, range_max, url_to_remove, presentation

filter_value

A specific value of a filter.

Access: filter., filter.false_value, filter.true_value, filter.max_value, filter.min_value

Properties: param_name, value, active, count, label, url_to_add, url_to_remove, swatch, image

font

A font from a font_picker setting.

Properties: family, fallback_families, baseline_ratio, weight, style, variants, system?

forloop

Information about a parent for loop.

Access: forloop.parentloop

Properties: length, parentloop, index, index0, rindex, rindex0, first, last

fulfillment

An order fulfillment, which includes information like the line items being fulfilled and shipment tracking.

Access: line_item.fulfillment

Properties: created_at, item_count, fulfillment_line_items, tracking_company, tracking_numbers, tracking_number, tracking_url

generic_file

A file from a file_reference type metafield that is neither an image or video.

Access: metafield.value

Properties: url, id, media_type, preview_image, position, alt

gift_card

A gift card that's been issued to a customer or a recipient.

Access: Templates: gift_card.liquid

Properties: balance, code, currency, customer, recipient, message, send_on, enabled, expired, expires_on, initial_value, url, template_suffix, properties, qr_identifier, pass_url, product, last_four_characters

group

A group of rules for the robots.txt file.

Access: robots.default_groups

Properties: user_agent, rules, sitemap

link

A link in a menu.

Access: linklist.links

Properties: active, current, child_active, child_current, handle, links, object, title, type, levels, url

linklist

A menu in a store.

Access: linklists.

Properties: links, handle, levels, title

localization

Information about the countries and languages that are available on a store.

Access: Global

Properties: available_countries, available_languages, market, country, language

location

A store location.

Access: store_availability.location

Properties: id, name, address, latitude, longitude, metafields

market

A group of one or more regions of the world that a merchant is targeting for sales.

Access: localization.market, country.market

Properties: id, handle, metafields

measurement

A measurement from one of the following metafield types:

• dimension
• volume
• weight

Access: metafield.value

Properties: type, value, unit

media

An abstract media object that can represent the following object types:

• image
• model
• video
• external_video

Access: product.media, product.featured_media, variant.featured_media, remote_product.featured_media

Properties: id, position, media_type, preview_image, alt

metafield

A metafield attached to a parent object.

Access: app.metafields, article.metafields, blog.metafields, collection.metafields, customer.metafields, location.metafields, order.metafields, page.metafields, product.metafields, shop.metafields, variant.metafields

Properties: value, type, list?

metaobject_system

Basic information about a metaobject. These properties are grouped under the system object to avoid collisions between system property names and user-defined metaobject fields.

Access: metaobject.system

Properties: type, handle, id, url

model

A 3D model uploaded as product media.

Access: product.media

Properties: sources, alt, id, media_type, position, preview_image

model_source

A model source file.

Access: model.

Properties: format, mime_type, url

paginate

Information about the pagination inside a set of paginate tags.

Properties: page_size, current_offset, current_page, items, parts, next, previous, pages, page_param

part

A part in the navigation for pagination.

Access: paginate.parts, paginate.next, paginate.previous

Properties: is_link, title, url

policy

A store policy, such as a privacy or return policy.

Access: shop.policies, remote_shop.shipping_policy, remote_shop.refund_policy, shop.refund_policy, shop.shipping_policy, shop.privacy_policy, shop.terms_of_service, shop.subscription_policy

Properties: id, body, url, title

predictive_search

Information about the results from a predictive search query through the Predictive Search API.

Properties: performed, resources, terms, types

predictive_search_resources

Contains arrays of objects for each resource type that can be returned by a predictive search query.

Access: predictive_search.resources

Properties: articles, collections, pages, products

product_option

A product option, such as size or color.

Access: product.options_with_values

Properties: name, position, values, selected_value

product_option_value

A product option value, such as "red" for the option "color".

Access: product_option.values, variant.options

Properties: id, name, swatch, selected, available, variant, product_url

quantity_rule

A variant order quantity rule.

Access: variant.quantity_rule

Properties: min, max, increment

rating

Information for a rating type metafield.

Access: metafield.value

Properties: rating, scale_min, scale_max

recipient

A recipient that is associated with a gift card.

Access: gift_card.recipient

Properties: nickname, email, name

recommendations

Product recommendations for a specific product based on sales data, product descriptions, and collection relationships.

Properties: performed?, products, products_count, intent

remote_product

A product that comes from a remote source, inheriting all product functionality and also providing additional context about the remote source.

Access: collection.products, line_item.product, search.results, variant.product

Properties: title, remote_details, featured_media, media, template_suffix, metafields, description, selling_plan_groups, options_with_values, category, variants, variants_count, id, vendor, content, featured_image, images, price_min, price, price_max, price_varies, selected_or_first_available_variant, selected_variant, first_available_variant, available, options, type, compare_at_price_min, compare_at_price_max, compare_at_price, compare_at_price_varies, url, published_at, created_at, options_by_name, has_only_default_variant, quantity_price_breaks_configured?, requires_selling_plan, selected_selling_plan, selected_selling_plan_allocation, selected_or_first_available_selling_plan_allocation, gift_card?

remote_shop

Information about a remote store.

Access: remote_product.remote_details, remote_details.shop

Properties: name, brand, shipping_policy, refund_policy, policies

request

Information about the current URL and the associated page.

Access: Global

Properties: design_mode, visual_preview_mode, page_type, host, origin, path, locale

routes

Allows you to generate standard URLs for the storefront.

Access: Global

Properties: root_url, account_url, account_login_url, account_logout_url, account_recover_url, account_register_url, account_addresses_url, account_profile_url, collections_url, all_products_collection_url, search_url, predictive_search_url, cart_url, cart_add_url, cart_change_url, cart_clear_url, cart_update_url, product_recommendations_url, storefront_login_url

search

Information about a storefront search query.

Access: Templates: search

Properties: terms, filters, performed, results, results_count, sort_options, sort_by, default_sort_by, types

selling_plan

Information about the intent of how a specific selling plan affects a line item.

Access: line_item.selling_plan_allocation, variant.selling_plan_allocations, product.selected_selling_plan, remote_product.selected_selling_plan, selling_plan_allocation.selling_plan

Properties: id, name, description, group_id, recurring_deliveries, options, price_adjustments, selected, checkout_charge

selling_plan_allocation

Information about how a specific selling plan affects a line item.

Access: line_item.selling_plan_allocation, variant.selling_plan_allocations, product.selected_selling_plan_allocation, product.selected_or_first_available_selling_plan_allocation, variant.selected_selling_plan_allocation, remote_product.selected_selling_plan_allocation, remote_product.selected_or_first_available_selling_plan_allocation

Properties: price, compare_at_price, price_adjustments, unit_price, per_delivery_price, selling_plan, selling_plan_group_id, checkout_charge_amount, remaining_balance_charge_amount

selling_plan_group

Information about a specific group of selling plans that include any of a product's variants.

Access: product.

Properties: selling_plans, id, name, app_id, options, selling_plan_selected

selling_plan_group_option

Information about a specific option in a selling plan group.

Access: selling_plan_group.

Properties: name, position, values, selected_value

selling_plan_option

Information about a selling plan's value for a specific selling_plan_group_option.

Access: selling_plan.options

Properties: name, position, value

selling_plan_price_adjustment

Information about how a selling plan changes the price of a variant for a given period of time.

Access: selling_plan_allocation.price_adjustments

Properties: order_count, position, value_type, value

shipping_method

Information about the shipping method for an order.

Access: checkout.shipping_method, order.shipping_method

Properties: title, original_price, price_with_discounts, handle, id, tax_lines, discount_allocations

shop_locale

A language in a store.

Access: localization.available_languages, localization.language, request.locale, shop.published_locales, shop.locale

Properties: name, endonym_name, iso_code, primary, root_url

store_availability

A variant's inventory information for a physical store location.

Access: variant.store_availabilities

Properties: available, pick_up_enabled, pick_up_time, location

tablerowloop

Information about a parent tablerow loop.

Properties: length, col, row, index, index0, col0, rindex, rindex0, first, last, col_first, col_last

tax_line

Information about a tax line of a checkout or order.

Access: checkout.tax_lines, order.tax_lines

Properties: title, price, rate, rate_percentage

taxonomy_category

The taxonomy category for a product

Access: product.category, remote_product.category

Properties: gid, id, name, ancestors

template

Information about the current template.

Access: Global

Properties: name, suffix, directory

theme (deprecated)

Information about the current theme.

Access: Global

Properties: id, name, role

transaction

A transaction associated with a checkout or order.

Access: checkout.transactions, order.transactions

Properties: id, name, status, created_at, receipt, kind, gateway, status_label, payment_details, amount, gateway_display_name, show_buyer_pending_payment_instructions?, buyer_pending_payment_notice, buyer_pending_payment_instructions

transaction_payment_details

Information about the payment methods used for a transaction.

Access: transaction.payment_details

Properties: credit_card_company, credit_card_last_four_digits, credit_card_number, gift_card

unit_price_measurement

Information about how units of a product variant are measured. It's used to calculate unit prices.

Access: line_item.unit_price_measurement, variant.unit_price_measurement

Properties: measured_type, quantity_value, quantity_unit, reference_value, reference_unit

user

The author of a blog article.

Access: article.user

Properties: account_owner, bio, email, first_name, homepage, image, last_name, name

video

Information about a video uploaded as product media or a file_reference metafield.

Access: metafield.value, product.media

Properties: sources, duration, aspect_ratio, alt, id, media_type, position, preview_image

video_source

Information about the source files for a video.

Access: video.sources

Properties: width, format, height, mime_type, url

Liquid Objects — Tier 3

53 simple objects with access paths.

`additional_checkout_buttons` (global) — Returns true if a store has any payment providers with offsite checkouts, such as PayPal Express C

`all_country_option_tags` (global) — Creates an <option> tag for each country.

`all_products` (global) — All of the products on a store.

`app` — An app. This object is usually used to access app-specific information for use with theme app extens

`articles` (global) — All of the articles across the blogs in the store.

`blogs` (global) — All of the blogs in the store.

`brand_color` (brand.colors) — The colors defined as part of a store's brand assets.

`canonical_url` (global) — The canonical URL for the current page.

`collections` (global) — All of the collections on a store.

`color_scheme` — A color_scheme from a color_scheme setting.

`color_scheme_group` — A color_scheme_group from a color_scheme_group setting.

`content_for_additional_checkout_buttons` (global) — Returns checkout buttons for any active payment providers with offsite checkouts.

`content_for_header` (global) — Dynamically returns all scripts required by Shopify.

`content_for_index` (global) — Dynamically returns the content of sections to be rendered on the home page.

`content_for_layout` (global) — Dynamically returns content based on the current template.

`country_option_tags` (global) — Creates an <option> tag for each country and region that's included in a shipping zone on the Ship

`current_page` (global) — The current page number.

`current_tags` (blog, collection) — The currently applied tags.

`customer_payment_method` (customer.payment_methods) — A customer's saved payment method.

`discount_allocation` (line_item.discount_allocations, shipping_method.discount_allocations) — Information about how a discount affects an item.

`filter_value_display` (deprecated) (filter_value.display) — The visual representation of a filter value.

`focal_point` (image_presentation.focal_point) — The focal point for an image.

`form_errors` (form.errors) — The error category strings for errors from a form created by a form tag.

`handle` (global) — The handle of the resource associated with the current template.

`image_presentation` (image.presentation) — The presentation settings for an image.

`images` (global) — All of the images that have been uploaded to a store.

`instructions` (line_item.instructions) — The instructions for a nested cart line item.

`linklists` (global) — All of the menus in a store.

`metaobject` (metaobjects.) — A metaobject entry, which includes the values for a set of fields. The set is defined by the parent

`metaobject_definition` — A metaobject_definition defines the structure of a metaobject type for the store, which consists o

`metaobjects` (global) — All of the metaobjects of the store.

`money` (metafield.value, store_credit_account.balance) — A money value, in the the customer's local (presentment) currency.

`page_description` (global) — The meta description of the current page.

`page_image` (global) — An image to be shown in search engine listings and social media previews for the current page.

`page_title` (global) — The page title of the current page.

`pages` (global) — All of the pages on a store.

`parent_relationship` (line_item.parent_relationship) — Information about the parent relationship for a nested cart line item.

`pending_payment_instruction_input` (transaction.buyer_pending_payment_instructions) — Header-value pairs that make up the list of payment information specific to the payment method. This

`powered_by_link` (global) — Creates an HTML link element that links to a localized version of shopify.com, based on the locale

`quantity_price_break` (variant.quantity_price_breaks) — The per-unit price of a variant when purchasing the minimum quantity or more.

`remote_details` (remote_product., remote_product.remote_details) — Information about the remote source from which the object came from.

`robots` (robots.txt.liquid) — The default rule groups for the robots.txt file.

`rule` (group.rules) — A rule for the robots.txt file, which tells crawlers which pages can, or can't, be accessed.

`script` (scripts.cart_calculate_line_items) — Information about a Shopify Script. > Caution: > Shopify Scripts will be sunset on August 28, 2025.

`scripts` (global) — The active scripts, of each script type, on the store. > Caution: > Shopify Scripts will be sunset o

`selling_plan_allocation_price_adjustment` (selling_plan_allocation.price_adjustments) — The resulting price from the intent of the associated selling_plan_price_adjustment.

`selling_plan_checkout_charge` (line_item.selling_plan_allocation, variant.selling_plan_allocations, selling_plan.checkout_charge) — Information about how a specific selling plan affects the amount that a customer needs to pay for a

`settings` (global) — Allows you to access all of the theme's settings from the settings_schema.json file.

`sitemap` (group.sitemap) — The sitemap for a specific group in the robots.txt file.

`sort_option` (collection.sort_options, search.sort_options) — A sort option for a collection or search results page.

`store_credit_account` (customer.store_credit_account, company_location.store_credit_account) — A store credit account owned by a customer.

`swatch` (product_option_value.swatch, filter_value.swatch) — Color and image for visual representation. Available for product option values and filter values.

`user_agent` (group.user_agent) — The user-agent, which is the name of the crawler, for a specific group in the robots.txt file.

Schema & Settings Reference

Section Schema Structure

The {% schema %} tag in sections accepts a JSON object with these top-level keys:

{
  "name": "t:sections.my_section.name",
  "tag": "section",
  "class": "my-section",
  "limit": 1,
  "settings": [],
  "max_blocks": 16,
  "blocks": [{ "type": "@theme" }],
  "presets": [{ "name": "t:sections.my_section.name" }],
  "enabled_on": { "templates": ["product"], "groups": ["header"] },
  "disabled_on": { "templates": ["password"] },
  "default": { "settings": {}, "blocks": [] },
  "locales": {}
}

Template values for `enabled_on`/`disabled_on`: *, 404, article, blog, captcha, cart, collection, customers/account, customers/activate_account, customers/addresses, customers/login, customers/order, customers/register, customers/reset_password, gift_card, index, list-collections, metaobject, page, password, policy, product, search

Block Schema Structure

The {% schema %} tag in theme blocks (.liquid files in blocks/):

{
  "name": "t:blocks.my_block.name",
  "tag": "div",
  "class": "my-block",
  "settings": [],
  "blocks": [{ "type": "@theme" }],
  "presets": [{ "name": "t:blocks.my_block.name" }]
}

Block Entry Types

In the blocks array of a section or block schema:

Setting Types (33 types)

Sidebar Settings (no id required)

These organize the editor UI — they don't produce values:

Input Settings (require id and label)

All input settings share these standard attributes:

Resource Pickers

Text Inputs

Number & Range

Boolean

Selection

Media

Color & Style

Navigation

Conditional Visibility (visible_if)

Most input settings support visible_if — a Liquid expression that controls whether the setting is shown in the theme editor:

{
  "type": "select",
  "id": "alignment",
  "label": "Alignment",
  "visible_if": "{{ block.settings.layout == 'vertical' }}",
  "options": [
    { "value": "left", "label": "Left" },
    { "value": "center", "label": "Center" }
  ]
}

The expression is evaluated against the current section/block settings. The setting is hidden (not removed) when the expression evaluates to false.

Not supported on: article, article_list, blog, collection, collection_list, metaobject, metaobject_list, page, product, product_list, color_scheme_group

Presets

Presets define default configurations that appear in the theme editor's "Add section/block" menu:

"presets": [
  {
    "name": "t:sections.hero.presets.default",
    "category": "t:categories.banner",
    "settings": {
      "heading": "Welcome",
      "height": 500
    },
    "blocks": [
      {
        "type": "text",
        "settings": { "text": "Hello" }
      }
    ]
  }
]