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, facets, and sort orders. Each is exposed as an SDK controller. The SDK handles request deduplication, the search_id lifecycle, 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. See the installation guide.
The Storefront Pixel installed so device and session identifiers are populated automatically.

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.query_text)}">${q.query_text}</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 })
  // Fire and forget - the SDK persists the search_id internally
  search.prepare()

  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()

Do not await prepare() on the critical path. It returns a result the SDK can keep working on in the background while you render the next page.

3. Get the search results

On the search results page, get() reuses the prepared search_id automatically. You do not need to pass it unless you are sharing it across pages via the URL. The SDK falls back to standard processing if the prepare cache 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 searchId = params.get('sid') || undefined

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({
  searchId,
  sort,
  pagination: { page },
  filterGroup: readActiveFiltersFromUrl(params),
})

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 hits enter. Create a search controller and call search.prepare() (non-blocking), then navigate to /search?q=.... The SDK persists the resulting search_id so the next page can use it.

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({ query, sort, filterGroup, pagination, searchId }). The SDK reuses 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 `search.prepare()`
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