Implementing search with the SDK

Overview

This is the SDK equivalent of Implementing search in Liquid. The same four moving pieces apply: autocomplete, prepare, get, and facets and sort orders. Each is exposed as an SDK controller. The SDK handles request deduplication, prepared search IDs, abort signals, and reactive state for you. Use this version when you have already installed @commerce-blocks/sdk in your theme. For a no-dependencies version, see the Liquid + Fetch guide.

Prerequisites

The Layers Shopify app installed and synced.
The SDK installed and initialized with storage when you need to reuse prepared search IDs across pages. See the installation guide.
The Storefront Pixel installed. The pixel owns device and session identifiers on the storefront; pass them to createSDK() through identity as a static object or resolver for SDK-issued requests.

Controllers used

Controller	Purpose
`sdk.autocomplete()`	Typeahead suggestions, including semantic redirects
`sdk.search()`	Prepare + get the full search request
`sdk.facets()`	Fetch facet counts for a search or collection
`sdk.sortOrders()`	Fetch available sort options

All expose the same reactive state and subscribe() shape as the collection controller.

1. Autocomplete in the header

autocomplete() fetches suggestions and supports semantic redirects. When a typed query matches a semantic redirect, data._meta.redirect.url is populated and you should navigate the shopper directly.

<form action="/search" method="get" role="search">
  <input type="search" name="q" autocomplete="off" id="search-input" />
  <ul id="search-suggestions" hidden></ul>
</form>

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

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

const input = document.getElementById('search-input')
const list = document.getElementById('search-suggestions')

let autocompleteController
const { call: debouncedSearch } = createDebounce(async (query) => {
  if (autocompleteController) autocompleteController.dispose()
  autocompleteController = sdk.autocomplete()

  autocompleteController.subscribe(({ data, error }) => {
    if (error) {
      console.error('Autocomplete failed:', error.message)
      return
    }
    if (!data) return

    if (data._meta?.redirect?.url) {
      window.location.href = data._meta.redirect.url
      return
    }

    list.innerHTML = data.matchedQueries
      .map(
        (q) =>
          `<li><a href="/search?q=${encodeURIComponent(q)}&original_query=${encodeURIComponent(query)}">${q}</a></li>`,
      )
      .join('')
    list.hidden = data.matchedQueries.length === 0
  })

  await autocompleteController.get({ query })
}, 200)

input.addEventListener('input', (event) => {
  const query = event.target.value.trim()
  if (!query) {
    list.hidden = true
    return
  }
  debouncedSearch(query)
})

The controller handles abort and deduplication internally. No manual AbortController plumbing is required.

2. Prepare the search before the results page

prepare() is a first-class method on sdk.search(). Call it the moment a shopper commits to a search. The SDK kicks off the request, caches the resulting search_id against the query, and get() automatically reuses it on the next page. Option A - Prepare on submit. Best when you can intercept the form submit so prepare keeps running during navigation.

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

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

const form = document.querySelector('form[role="search"]')

form.addEventListener('submit', async (event) => {
  event.preventDefault()
  const query = form.q.value.trim()
  if (!query) return

  const search = sdk.search({ query })
  const { error } = await search.prepare()
  if (error) {
    console.error('Prepare failed:', error.message)
    return
  }

  window.location.href = `/search?q=${encodeURIComponent(query)}`
})

Option B - Prepare on the search results page. Simpler, but loses the in-flight head start.

<script>window.layersSearchQuery = {{ search.terms | json }}</script>

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

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

const search = sdk.search({ query: window.layersSearchQuery })
await search.prepare()

Awaiting prepare() before navigation is what persists the prepared search_id for cross-page reuse. If you cannot await it, the results page still works, but it repeats the prepare step.

The SDK resolves the prepared search_id itself — get() does not read a search_id from the URL, so a shopper landing on a shared link without a matching prepare entry gets standard processing. Still put it there (/search?q=...&search_id=...) for pixel attribution on shared or bookmarked links — note the prepared cache is not reused on a fresh visit, so the ID in the URL preserves attribution, not speed. Also add original_query when an autocomplete suggestion click — rather than typed input — drove the search, so analytics can attribute the executed suggestion to what the shopper typed. The storefront pixel treats both as first-class URL parameters.

3. Get the search results

On the search results page, get() resolves the prepared search_id automatically when the query and request parameters match. You do not need to read an ID from the URL or pass one to get(). The SDK falls back to standard processing if the prepare entry has expired or no prepare ran.

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

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

const params = new URLSearchParams(location.search)
const query = params.get('q') || ''
const sort = params.get('sort') || undefined
const page = Number(params.get('page')) || 1

const search = sdk.search({ query })

search.subscribe(({ data, loading, error }) => {
  if (loading) showLoading()
  if (error) showError(error.message)
  if (data) {
    renderGrid(data.products)
    renderFacets(data.facets, data.facetRanges)
    renderPagination(data.page, data.totalPages)
  }
})

await search.get({
  sort,
  pagination: { page },
  filterGroup: readActiveFiltersFromUrl(params),
})

Render the results page frame — title, search bar, sort/facet controls, and a skeleton grid — in Liquid so the first paint is complete, then hydrate in place. Injecting the frame from JS causes layout shift and hides the search bar while scripts load. For result cards, render tiles through the theme’s own card snippet via the Section Rendering API rather than a client-side card renderer.

A simple readActiveFiltersFromUrl helper builds a filter group from URL parameters. Replace the attribute names with the codes configured in your Layers dashboard:

function readActiveFiltersFromUrl(params) {
  const expressions = []
  for (const [key, value] of params.entries()) {
    if (key.startsWith('filter_')) {
      const attribute = key.replace('filter_', '')
      expressions.push(eq(attribute, value))
    }
  }
  return expressions.length > 0 ? filter(and(...expressions)) : undefined
}

Controller options merge across calls, so subsequent interactions only pass what is changing:

search.get({ sort: 'price-asc', pagination: { page: 1 } }) // change sort, reset page
search.get({ filterGroup: filter(eq('your-attribute', 'your-value')) }) // add filter, keep sort
search.get({ pagination: { page: 2 } }) // pagination, keep everything else

In v3, sort orders and facets are not configured at SDK init. Fetch them at runtime with sdk.sortOrders() and sdk.facets().

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

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

// Sort dropdown
const sortController = sdk.sortOrders()
const { data: sortData, error: sortError } = await sortController.get()
if (!sortError && sortData) {
  renderSortDropdown(sortData.sortOrders)
}

// Facet counts
const facetController = sdk.facets({ collectionHandle: 'search' })
const { data: facetData, error: facetError } = await facetController.get()
if (!facetError && facetData) {
  renderFacets(facetData.facets, facetData.facetRanges)
}

You can also request filtered facet counts by passing the active filterGroup:

await facetController.get({
  filterGroup: filter(and(eq('your-attribute', 'your-value'))),
})

Recommended request flow

The end-to-end timeline:

Header submit

Shopper presses enter. Create a search controller and await search.prepare() before navigating to /search?q=.... Cross-page reuse requires storage in createSDK(). The results page resolves the prepared search_id itself.

Results page render

Render the sort dropdown and empty facet groups from sdk.sortOrders() and sdk.facets(), including the active sort/filter state from the URL.

Get results

Page JS calls search.get({ sort, filterGroup, pagination }) — query is fixed when the controller is created. The SDK resolves the prepared search_id automatically. The subscriber renders the grid, facets, and pagination as soon as data lands.

Interaction

On sort change or filter toggle, call search.get({ ... }) with just the changed fields. Mirror the state to the URL via history.replaceState.

Why the SDK over Fetch

Concern	Fetch version	SDK version
Debounced autocomplete	DIY debounce + `AbortController`	`createDebounce()` + `autocomplete()`
`search_id` lifecycle	`sessionStorage` plumbing across pages	Handled internally by `prepare()`/`get()`; set `storage` for cross-page reuse
Re-renders	DIY DOM updates	`subscribe()` callback
Sticky options	Track manually	Shallow-merged by `get()`
Click feedback / attribution	Read `attributionToken`, POST to feedback endpoint	Storefront Pixel handles standard themes; SDK exposes `attributionToken` on results for custom flows
Errors	Hand `try/catch`	`{ data, error }` with `ApiError` for HTTP failures

Troubleshooting

Suggestions show but redirects do not fire. The redirect lives at data._meta.redirect.url on the autocomplete state. Make sure your subscriber checks for it before rendering the suggestion list. get() is slow on the results page. Prepare was not called, or the cache has expired. The SDK falls back to normal processing. Confirm prepare runs before navigation. Filters do not apply. Attribute codes in filterGroup must exactly match the codes configured as facets in Layers. Fetch sdk.facets() to verify the codes.

Liquid Integration

Liquid + Fetch guides

Liquid + SDK guides

Implementing search with the SDK

Overview

Prerequisites

Controllers used

1. Autocomplete in the header

2. Prepare the search before the results page

3. Get the search results

4. Render facet and sort controls at runtime

Recommended request flow

Why the SDK over Fetch

Troubleshooting

See also

​Overview

​Prerequisites

​Controllers used

​1. Autocomplete in the header

​2. Prepare the search before the results page

​3. Get the search results

​4. Render facet and sort controls at runtime

​Recommended request flow

​Why the SDK over Fetch

​Troubleshooting

​See also

Overview

Prerequisites

Controllers used

1. Autocomplete in the header

2. Prepare the search before the results page

3. Get the search results

4. Render facet and sort controls at runtime

Recommended request flow

Why the SDK over Fetch

Troubleshooting

See also