Metafields Reference & Liquid

Smart Collection Pro stores your collection hierarchy as metafields — parent/child relationships, depth levels, root collections, and breadcrumb priorities. These metafields are kept in sync automatically whenever you update your tree in the app.

When should you use metafields?

For most stores, the built-in app blocks (Collection Grid, Breadcrumbs, etc.) are the easiest way to display your hierarchy — no code required. We recommend starting there.

That said, metafields give you full flexibility when you need it. They're a great fit if:

You have a development team that needs to integrate the hierarchy into a custom theme with specific styling or layout requirements.
You need hierarchy data in places the app blocks don't cover — like Liquid email templates, third-party page builders, or headless storefronts.
You want to build something custom, like a mega-menu or a dynamic navigation, powered by your collection tree.

Good to know: These metafields aren't limited to Liquid templates. They're standard Shopify metafields, so they're also available through the Storefront API and the Admin API — useful for headless builds, custom apps, or any workflow that reads metafield data.

Available Metafields

All metafields live under the namespace app--162129281025.

Collection metafields

These are set on each collection resource.

Metafield key	Type	Description
`parent_collection`	`collection_reference`	The direct parent of this collection. Blank for root collections.
`children_collections`	`list.collection_reference`	Ordered list of direct child collections.
`depth`	`number_integer`	How deep the collection sits in the tree. Root collections have a depth of 1, their children 2, and so on.
`breadcrumb_priority`	`number_integer`	The priority value you configured in the app's Breadcrumbs settings (Shopify Admin → Smart Collection Pro → Breadcrumbs). Lower numbers mean higher priority. This helps pick the best breadcrumb path when a product belongs to multiple collections.

Shop metafields

These are set on the shop resource and give you access to your root-level collections.

Metafield key	Type	Description
`root_collections_1`	`list.collection_reference`	First batch of root collections (up to 250).
`root_collections_2`	`list.collection_reference`	Second batch (items 251–500).
`root_collections_3`	`list.collection_reference`	Third batch (items 501–750).
`root_collections_4`	`list.collection_reference`	Fourth batch (items 751–1000).

Root collections are split across multiple metafields because Shopify limits list metafields to 250 items each. Most stores will only need root_collections_1.

Accessing Metafields in Liquid

In Liquid, you reference the namespace using bracket notation:

{{ collection.metafields['app--162129281025'].depth }}
{{ collection.metafields['app--162129281025'].parent_collection.value }}
{{ collection.metafields['app--162129281025'].children_collections.value }}

For shop-level metafields:

{{ shop.metafields['app--162129281025'].root_collections_1.value }}

Examples

Here are a few common patterns to get you started.

Display child collections on a collection page

This is useful when you want to show subcategory cards above your product list — for example, showing "Beachwear", "Sunglasses", and "Hats" on your "Summer Sale" collection page.

{% assign children = collection.metafields['app--162129281025'].children_collections.value %}

{% if children.size > 0 %}
  <ul class="subcategory-grid">
    {% for child in children %}
      <li>
        <a href="{{ child.url }}">
          {% if child.featured_image %}
            {{ child.featured_image
              | image_url: width: 600
              | image_tag: loading: 'lazy' }}
          {% endif %}
          <span>{{ child.title }}</span>
        </a>
      </li>
    {% endfor %}
  </ul>
{% endif %}

List all root collections

If you need to display your top-level collections — for example in a custom navigation or on your homepage — you can pull them from the shop metafields:

{% assign roots = shop.metafields['app--162129281025'].root_collections_1.value %}

{%- comment -%}
  If your store has more than 250 root collections, concatenate the additional batches:
  {% assign batch_2 = shop.metafields['app--162129281025'].root_collections_2.value %}
  {% assign roots = roots | concat: batch_2 %}
{%- endcomment -%}

<ul>
  {% for col in roots %}
    <li><a href="{{ col.url }}">{{ col.title }}</a></li>
  {% endfor %}
</ul>

You can walk up the tree using parent_collection to build a breadcrumb trail like Home › Summer Sale › Beachwear:

{% assign crumbs = '' | split: '' %}
{% assign current = collection %}

{% for i in (1..10) %}
  {% assign crumbs = crumbs | unshift: current %}
  {% assign current = current.metafields['app--162129281025'].parent_collection.value %}
  {% if current == blank %}
    {% break %}
  {% endif %}
{% endfor %}

<nav aria-label="Breadcrumb">
  <ol>
    <li><a href="/">Home</a></li>
    {% for crumb in crumbs %}
      {% if crumb == collection %}
        <li aria-current="page">{{ crumb.title }}</li>
      {% else %}
        <li><a href="{{ crumb.url }}">{{ crumb.title }}</a></li>
      {% endif %}
    {% endfor %}
  </ol>
</nav>

Products often belong to multiple collections. For example, a pair of sneakers might be in both "Women › Shoes › Sneakers" and "New Arrivals". You probably want the breadcrumb to show the deeper, more specific path.

The breadcrumb_priority metafield (which you configure in the app under Breadcrumbs) and depth help you pick the right one — lower priority wins first, and if two collections share the same priority, the deeper one is preferred:

{% assign best_collection = nil %}
{% assign best_priority = nil %}
{% assign best_depth = nil %}

{% for col in product.collections %}
  {% assign depth = col.metafields['app--162129281025'].depth %}
  {% assign priority = col.metafields['app--162129281025'].breadcrumb_priority %}

  {% if depth >= 1 %}
    {% assign is_better = false %}

    {% comment %} Prefer lower priority value (= higher importance) {% endcomment %}
    {% if priority != blank %}
      {% if best_priority == blank or priority < best_priority %}
        {% assign is_better = true %}
      {% endif %}
    {% endif %}

    {% comment %} Same priority? Prefer deeper collection {% endcomment %}
    {% if priority == best_priority and depth > best_depth %}
      {% assign is_better = true %}
    {% endif %}

    {% if best_depth == blank or is_better %}
      {% assign best_priority = priority %}
      {% assign best_depth = depth %}
      {% assign best_collection = col %}
    {% endif %}
  {% endif %}
{% endfor %}

{% comment %}
  Now build the breadcrumb by walking up from best_collection
  using parent_collection, same technique as the collection breadcrumb above.
{% endcomment %}

Adapt layout based on collection depth

You can use depth for conditional logic — for example, showing a different layout depending on where a collection sits in the tree:

{% assign depth = collection.metafields['app--162129281025'].depth %}

{% if depth == 1 %}
  {% comment %} Root collection — show a large hero banner {% endcomment %}
{% elsif depth >= 3 %}
  {% comment %} Deep collection — show a compact header {% endcomment %}
{% endif %}

When should you use metafields?​

Available Metafields​

Collection metafields​

Shop metafields​

Accessing Metafields in Liquid​

Examples​

Display child collections on a collection page​

List all root collections​

Build a collection page breadcrumb​

Pick the best breadcrumb collection for a product page​

Adapt layout based on collection depth​