Overview
Layers metaobjects and metafields are accessible in your Shopify theme via Liquid, allowing you to build custom sort order selectors, facet filters, and recommendation blocks without JavaScript. All Layers metaobjects have public storefront access, making them available in any Liquid template.
Namespace Reference
Layers uses the following namespaces for metaobjects:
| Resource | Namespace |
|---|
| Sort Orders | app--278936322049--sort_order |
| Facets | app--278936322049--facet |
| Blocks | app--278936322049--block |
| Collection Metafields | layers |
| App Installation Metafields | layers |
Accessing Sort Orders
Sort order metaobjects represent the sort orders configured in your Layers dashboard.
Basic Access
{% assign layers_sort_metaobjects = shop.metaobjects['app--278936322049--sort_order'] %}
<select name="sort_order">
{% for sort_order in layers_sort_metaobjects %}
<option value="{{ sort_order.code.value }}">
{{ sort_order.name.value }}
</option>
{% endfor %}
</select>
Available Fields
| Field | Type | Description |
|---|
| name | string | Display name of the sort order |
| code | string | Unique code identifier |
| scope | array | Contexts where available (search, collection) |
| order | integer | Display order |
Filtering by Scope
Display only sort orders available for specific contexts:
{% assign layers_sort_metaobjects = shop.metaobjects['app--278936322049--sort_order'] %}
<!-- Collection page sort orders -->
<select name="sort_order">
{% for sort_order in layers_sort_metaobjects %}
{% assign scopes = sort_order.scope.value %}
{% if scopes contains 'collection' %}
<option value="{{ sort_order.code.value }}">
{{ sort_order.name.value }}
</option>
{% endif %}
{% endfor %}
</select>
Ordering by Display Order
{% assign layers_sort_metaobjects = shop.metaobjects['app--278936322049--sort_order'] %}
{% assign sorted_orders = layers_sort_metaobjects | sort: 'order' %}
<ul class="sort-options">
{% for sort_order in sorted_orders %}
<li data-code="{{ sort_order.code.value }}">
{{ sort_order.name.value }}
</li>
{% endfor %}
</ul>
Using Collection Default Sort Order
Access the default sort order assigned to a collection:
{% assign default_sort_code = nil %}
{% if collection.metafields.layers.default_sort_order %}
{% assign default_sort_code = collection.metafields.layers.default_sort_order.value.code.value %}
{% endif %}
{% assign layers_sort_metaobjects = shop.metaobjects['app--278936322049--sort_order'] %}
<select name="sort_order">
{% for sort_order in layers_sort_metaobjects %}
<option
value="{{ sort_order.code.value }}"
{% if sort_order.code.value == default_sort_code %}selected{% endif %}
>
{{ sort_order.name.value }}
</option>
{% endfor %}
</select>
Accessing Facets
Facet metaobjects represent filterable attributes configured in Layers.
Basic Access
{% assign layers_facet_metaobjects = shop.metaobjects['app--278936322049--facet'] %}
<div class="facet-list">
{% for facet in layers_facet_metaobjects %}
<div class="facet" data-code="{{ facet.code.value }}">
<h3>{{ facet.name.value }}</h3>
</div>
{% endfor %}
</div>
Available Fields
| Field | Type | Description |
|---|
| name | string | Display name of the facet |
| code | string | Unique code identifier |
Building a Facet Filter UI
{% assign layers_facet_metaobjects = shop.metaobjects['app--278936322049--facet'] %}
<aside class="filters">
<h2>Filter by</h2>
{% for facet in layers_facet_metaobjects %}
<div class="filter-group">
<h3>{{ facet.name.value }}</h3>
<div class="filter-options" data-facet="{{ facet.code.value }}">
<!-- Facet values populated via JavaScript from Layers API -->
</div>
</div>
{% endfor %}
</aside>
Facet metaobjects only provide the facet configuration (name and code). Actual facet values and counts must be fetched from the Layers Browse API.
Accessing Blocks
Block metaobjects represent recommendation blocks configured in Layers.
Basic Access
{% assign layers_blocks = shop.metaobjects['app--278936322049--block'] %}
{% for block in layers_blocks %}
<div class="recommendation-block" data-block-handle="{{ block.handle }}">
<h2>{{ block.title.value }}</h2>
<!-- Block content populated via JavaScript from Layers API -->
</div>
{% endfor %}
Available Fields
| Field | Type | Description |
|---|
| label | string | Display label (formatted as “Title - AnchorType”) |
| title | string | Block title |
| anchor_type | string | Anchor type (product, collection, cart, none) |
Filtering by Anchor Type
Display blocks based on the current page context:
{% assign layers_blocks = shop.metaobjects['app--278936322049--block'] %}
<!-- Collection pages -->
{% if template == 'collection' %}
{% for block in layers_blocks %}
{% if block.anchor_type.value == 'collection' %}
<div class="recommendation-block" data-block-handle="{{ block.handle }}">
<h2>{{ block.title.value }}</h2>
</div>
{% endif %}
{% endfor %}
{% endif %}
<!-- Product pages -->
{% if template == 'product' %}
{% for block in layers_blocks %}
{% if block.anchor_type.value == 'product' %}
<div class="recommendation-block" data-block-handle="{{ block.handle }}">
<h2>{{ block.title.value }}</h2>
</div>
{% endif %}
{% endfor %}
{% endif %}
Accessing App Configuration
Access Layers configuration data stored on the app installation.
Embed Settings
{% assign embed_settings = shop.metafields.layers.embed_settings.value %}
<script>
window.layersConfig = {
apiToken: '{{ embed_settings.apiToken }}',
storefrontApiToken: '{{ embed_settings.storefrontApiToken }}'
};
</script>
Available Fields
| Field | Type | Description |
|---|
| apiToken | string | Analytics tracking token |
| storefrontApiToken | string | Storefront API token |
| integrations | object | Enabled integrations and their configurations |
| sessionCookieFallbacks | array | Cookie names for session identification |
Best Practices
- Cache metaobject queries when possible using Liquid variables
- Minimize the number of metaobject iterations in your templates
- Use JavaScript to fetch dynamic data (facet values, recommendations) rather than making multiple Liquid queries
Error Handling
Always check if metaobjects exist before accessing them:
{% if shop.metaobjects['app--278936322049--sort_order'] %}
{% assign layers_sort_metaobjects = shop.metaobjects['app--278936322049--sort_order'] %}
<!-- Your code here -->
{% endif %}
Namespace Consistency
Use the exact namespace values provided in this documentation. The namespace includes the Layers app ID and must match exactly:
{% comment %} Correct {% endcomment %}
{% assign layers_sort_metaobjects = shop.metaobjects['app--278936322049--sort_order'] %}
{% comment %} Incorrect {% endcomment %}
{% assign layers_sort_metaobjects = shop.metaobjects['$app:sort_order'] %}
The $app placeholder in metaobject type definitions is replaced with app--278936322049 in Liquid. Always use the full namespace when accessing metaobjects via Liquid.
Troubleshooting
If metaobjects are not accessible in Liquid:
- Verify the sort order has Enable as Storefront Sort enabled in Layers
- Verify the facet has Enable as Storefront Facet enabled in Layers
- Check that the metaobject was created (visible in Shopify admin under Content → Metaobjects)
- Ensure you’re using the correct namespace
Empty Values
If metaobject fields return empty values:
- Verify the field exists in the Layers dashboard
- Check that the metaobject has been synced (may take a few seconds after creation)
- Use
.value to access field values: {{ sort_order.name.value }}
Collection Default Sort Order Not Found
If the collection’s default sort order is not accessible:
- Verify a default sort order is assigned in Shopify admin (Products → Collections → [Collection] → Metafields)
- Check that the referenced sort order still exists in Layers
- Ensure you’re using the correct metafield namespace
See Also
