Rendering facets with the SDK

Overview

This is the SDK equivalent of Rendering facets in Liquid. The pattern is the same: read facet metaobjects in Liquid, then resolve runtime facet values, counts, and ranges from Layers. The SDK’s facets() controller handles the HTTP request, request deduplication, caching, abort signals, and filter-group transformation for you, and exposes results as reactive state you can subscribe to. Use this version when you have already installed @commerce-blocks/sdk in your theme. If you are scripting against the storefront API directly with fetch, see the vanilla Liquid + Fetch guide instead.

Prerequisites

The Layers Shopify app installed and synced.
Facets configured in the Layers dashboard with Enable as Storefront Facet turned on.
The SDK installed and initialized in your theme. See SDK installation.

The pattern

Read facet metaobjects in Liquid

Render the sidebar shell from metaobjects exactly like the Fetch version. Each <section> carries the facet code so the SDK results can be matched to the right group.

{% assign layers_facets = shop.metaobjects['app--278936322049--facet'] %}

<aside class="filters" data-collection="{{ collection.handle }}">
  <h2>Filter by</h2>
  {% for facet in layers_facets %}
    <section class="filter-group" data-facet-code="{{ facet.code.value }}">
      <h3>{{ facet.name.value }}</h3>
      <div class="filter-values" data-loading="true"></div>
    </section>
  {% endfor %}
</aside>

Create a facets controller

sdk.facets() returns a reactive controller. Its state updates every time get() runs, and the SDK deduplicates identical in-flight requests and caches results.

import { getSDK } from '@commerce-blocks/sdk'

const { data: sdk, error: sdkError } = getSDK()
if (sdkError) {
  console.error('SDK not initialized:', sdkError.message)
}

const sidebar = document.querySelector('.filters')
const collectionHandle = sidebar.dataset.collection
const facetsController = sdk.facets({ collectionHandle })

facetsController.subscribe(({ data, loading, error }) => {
  if (loading) sidebar.dataset.loading = 'true'
  else delete sidebar.dataset.loading

  if (error) {
    console.error('Facet fetch failed:', error.message)
    return
  }
  if (data) renderFacets(data.facets, data.facetRanges)
})

Render values, counts, and ranges

The render code looks at the same data-facet-code attributes as the Fetch version.

function renderFacets(facets, facetRanges) {
  sidebar.querySelectorAll('[data-facet-code]').forEach((group) => {
    const code = group.dataset.facetCode
    const container = group.querySelector('.filter-values')
    container.removeAttribute('data-loading')

    // Numeric range facets, e.g. variants.price
    if (facetRanges?.[code]) {
      const { min, max } = facetRanges[code]
      container.innerHTML = `
        <input type="range" name="min" min="${min}" max="${max}" value="${min}" />
        <input type="range" name="max" min="${min}" max="${max}" value="${max}" />
        <output>${min} - ${max}</output>
      `
      return
    }

    const values = facets?.[code]
    if (!values) {
      group.hidden = true // no available values for this collection
      return
    }

    container.innerHTML = Object.entries(values)
      .map(
        ([value, count]) => `
          <label>
            <input type="checkbox" name="${code}" value="${value}" />
            ${value} <span class="count">(${count})</span>
          </label>
        `,
      )
      .join('')
  })
}

Execute the initial load

Trigger the first request. The subscriber above renders the sidebar as soon as data lands.

await facetsController.get()

Refreshing counts as filters are applied

Call facetsController.get({ filterGroup }) whenever the active selection changes. The SDK reuses the same controller, deduplicates in-flight requests, and updates the state. Then pass the same filterGroup to the collection controller so the product grid updates too.

import { getSDK, filter, and, or, eq, inValues } from '@commerce-blocks/sdk'

const { data: sdk, error: sdkError } = getSDK()
if (sdkError) {
  console.error('SDK not initialized:', sdkError.message)
}

const collection = sdk.collection({ collectionHandle })

sidebar.addEventListener('change', () => {
  const selected = {}
  sidebar.querySelectorAll('input[type="checkbox"]:checked').forEach((input) => {
    selected[input.name] ??= []
    selected[input.name].push(input.value)
  })

  const expressions = Object.entries(selected).map(([code, values]) =>
    values.length > 1 ? inValues(code, values) : eq(code, values[0]),
  )

  const filterGroup = expressions.length > 0 ? filter(and(...expressions)) : undefined

  facetsController.get({ filterGroup })
  collection.get({ filterGroup })
})

For multi-value selections, the SDK applies OR within a facet and AND across facets automatically when you use the filter DSL. You can also request facet counts directly on a collection request by passing facets and retrieveFacetCount:

const collection = sdk.collection({ collectionHandle })

await collection.get({
  facets: ['your-attribute-1', 'your-attribute-2'],
  retrieveFacetCount: true,
  includeFacetRanges: true,
})

The response includes data.facets and data.facetRanges alongside the product list. For complex pages, using a dedicated sdk.facets() controller keeps product and facet requests independent and easier to manage.

Why the SDK over Fetch

Concern	Fetch version	SDK version
Request body shape	Hand-rolled `filter_group`	Filter DSL with `filter()`, `and()`, `or()`, etc.
Counts and ranges	Opt in via `retrieveFacetCount` / `includeFacetRanges`	Dedicated `sdk.facets()` controller
Caching	DIY	Built-in cache with TTL and `localStorage` persistence
Deduplication	DIY	Built-in
Abort handling	DIY `AbortController`	Built-in per-controller
Reactivity	DIY	`subscribe()` callback

If you have any one of these needs, the SDK saves you the boilerplate. The Fetch version remains useful when you want zero dependencies.

Troubleshooting

data.facets is empty. Confirm the facets you expect are configured as storefront facets in the Layers dashboard. Also confirm you passed the collectionHandle to sdk.facets(). Counts do not change when filters are applied. Make sure you pass the active filterGroup to both the collection controller and the facets controller. The SDK does not watch the DOM. Subscribe to each controller state and re-render on every emit. data.facetRanges is empty. Pass includeFacetRanges: true and include the numeric facet code in the facets array.

Liquid Integration

Liquid + Fetch guides

Liquid + SDK guides

Rendering facets with the SDK

Overview

Prerequisites

The pattern

Refreshing counts as filters are applied

Collection + facets together

Why the SDK over Fetch

Troubleshooting

See also

​Overview

​Prerequisites

​The pattern

​Refreshing counts as filters are applied

​Collection + facets together

​Why the SDK over Fetch

​Troubleshooting

​See also

Overview

Prerequisites

The pattern

Refreshing counts as filters are applied

Collection + facets together

Why the SDK over Fetch

Troubleshooting

See also