> ## Documentation Index
> Fetch the complete documentation index at: https://docs.uselayers.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Liquid integration

> How to access Layers metaobjects, metafields, and configuration values directly in your Shopify theme using Liquid templates and snippet helpers.

## 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

```liquid theme={null}
{% 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:

```liquid theme={null}
{% 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

```liquid theme={null}
{% 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:

```liquid theme={null}
{% 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

```liquid theme={null}
{% 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

```liquid theme={null}
{% 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>
```

<Note>
  Facet metaobjects only provide the facet configuration (name and code). Actual facet values and counts must be fetched from the Layers Browse API.
</Note>

## Accessing blocks

Block metaobjects represent recommendation blocks configured in Layers.

### Basic access

```liquid theme={null}
{% 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:

```liquid theme={null}
{% 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

```liquid theme={null}
{% 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

### Performance

* 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:

```liquid theme={null}
{% 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:

```liquid theme={null}
{% comment %} Correct {% endcomment %}
{% assign layers_sort_metaobjects = shop.metaobjects['app--278936322049--sort_order'] %}

{% comment %} Incorrect — missing the app ID prefix {% endcomment %}
{% assign layers_sort_metaobjects = shop.metaobjects['sort_order'] %}
```

<Note>
  Always use the full namespace (`app--278936322049--<type>`) when accessing Layers metaobjects via Liquid. Short forms or aliases will not resolve.
</Note>

## Troubleshooting

### Metaobjects not appearing

If metaobjects are not accessible in Liquid:

1. Verify the sort order has **Enable as Storefront Sort** enabled in Layers
2. Verify the facet has **Enable as Storefront Facet** enabled in Layers
3. Check that the metaobject was created (visible in Shopify admin under Content → Metaobjects)
4. Ensure you're using the correct namespace

### Empty values

If metaobject fields return empty values:

1. Verify the field exists in the Layers dashboard
2. Check that the metaobject has been synced (may take a few seconds after creation)
3. 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:

1. Verify a default sort order is assigned in Shopify admin (Products → Collections → \[Collection] → Metafields)
2. Check that the referenced sort order still exists in Layers
3. Ensure you're using the correct metafield namespace

## See also

* [Metaobjects & Metafields](/shopify-integration/metaobjects-metafields) - Complete reference for Layers metaobjects
* [SDK Reference](/sdk/overview) - JavaScript SDK for Layers integration
* [Browse API](/api-reference/browse) - Fetch products with sorting and filtering
* [Blocks API](/api-reference/blocks) - Fetch recommendation blocks