Rendering sort orders with the SDK

Overview

This is the SDK equivalent of Rendering sort orders in Liquid. You still render the dropdown from sort metaobjects in Liquid so the UI stays in sync with the dashboard. Pass the selected code to the SDK’s collection() or search() controller as sort instead of issuing the API request yourself. 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

Sort orders configured in the Layers dashboard with Enable as Storefront Sort turned on.
The SDK installed and initialized in your theme. See SDK installation.

Render the dropdown from sort metaobjects

Filter by the collection scope and order by the configured order field. Read the collection’s default sort from layers.default_sort_order and the active sort from the URL.

{% assign layers_sorts = shop.metaobjects['app--278936322049--sort_order'] | sort: 'order' %}

{% 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 active_sort_code = request.params.sort | default: default_sort_code %}

<label for="sort-order">Sort by</label>
<select
  id="sort-order"
  name="sort"
  data-collection="{{ collection.handle }}"
  data-default-sort="{{ default_sort_code }}"
>
  {% for sort in layers_sorts %}
    {% assign scopes = sort.scope.value %}
    {% if scopes contains 'collection' %}
      <option
        value="{{ sort.code.value }}"
        {% if sort.code.value == active_sort_code %}selected{% endif %}
      >
        {{ sort.name.value }}
      </option>
    {% endif %}
  {% endfor %}
</select>

Drive a collection controller from the dropdown

Create the controller once, subscribe to render, and call get({ sort }) whenever the selection changes. The SDK deduplicates in-flight requests and updates the state. Subscribers re-render automatically.

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

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

const select = document.querySelector('#sort-order')
const collectionHandle = select.dataset.collection
const defaultSort = select.dataset.defaultSort || undefined

const collection = sdk.collection({ collectionHandle, sort: defaultSort })

collection.subscribe(({ data, loading }) => {
  if (loading) showLoading()
  if (data) renderGrid(data.products)
})

// Initial load - uses the option pre-selected by Liquid
await collection.get()

select.addEventListener('change', (event) => {
  const sortCode = event.target.value || undefined
  collection.get({ sort: sortCode })

  // Mirror selection to the URL so it survives refresh and back navigation
  const url = new URL(window.location.href)
  if (sortCode) url.searchParams.set('sort', sortCode)
  else url.searchParams.delete('sort')
  window.history.replaceState({}, '', url)
})

Passing sort to the controller sets the default. Call get({ sort: undefined }) to fall back to that default, or pass a new sort to override it.

The pattern is identical. Filter the metaobjects by the search scope and drive an sdk.search() controller instead.

{% assign layers_sorts = shop.metaobjects['app--278936322049--sort_order'] | sort: 'order' %}

<select id="search-sort" name="sort">
  <option value="">Relevance</option>
  {% for sort in layers_sorts %}
    {% assign scopes = sort.scope.value %}
    {% if scopes contains 'search' %}
      <option value="{{ sort.code.value }}">{{ sort.name.value }}</option>
    {% endif %}
  {% endfor %}
</select>

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

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

const query = new URLSearchParams(location.search).get('q') ?? ''
const search = sdk.search({ query })

search.subscribe(({ data }) => {
  if (data) renderGrid(data.products)
})

await search.get({ sort: undefined }) // relevance

document.querySelector('#search-sort').addEventListener('change', (event) => {
  search.get({ sort: event.target.value || undefined })
})

Leave the first option blank (or label it “Relevance”) on search pages. Omitting sort lets Layers rank by relevance, which is usually what shoppers want for a typed query.

Fetching sort orders at runtime

If you do not want to render the dropdown from Liquid metaobjects, you can fetch available sort orders at runtime with sdk.sortOrders():

const sortController = sdk.sortOrders()
const { data, error } = await sortController.get()
if (error) {
  console.error('Sort orders fetch failed:', error.message)
} else if (data) {
  renderSortDropdown(data.sortOrders)
}

Combining sort with filters and pagination

Controller options shallow-merge across get() calls. Passing only the field you want to change keeps the rest sticky.

// Page 2 of the current sort
collection.get({ pagination: { page: 2 } })

// New sort, same filters, reset page to 1
collection.get({ sort: 'price-asc', pagination: { page: 1 } })

// Same sort, additional filter
collection.get({ filterGroup: filter(eq('your-attribute', 'your-value')) })

Default sort orders

Surface	Default source
Collection	`sort` passed to `sdk.collection()` at creation → falls back to the collection’s `layers.default_sort_order` metafield → falls back to the store default
Search	Relevance

Pass the metafield-resolved code (read in Liquid) as sort to the controller so the SDK and the rendered dropdown agree on the default.

Why the SDK over Fetch

Concern	Fetch version	SDK version
Driving the request	Hand-rolled `fetch` to `/browse` or `/search`	`controller.get({ sort })`
Re-renders	DIY DOM updates	`subscribe()` callback
Sticky options	Track manually	Shallow-merged automatically across calls
Caching across nav	DIY	Restored from `localStorage`

Troubleshooting

Selecting a sort does not change the grid. Confirm the subscriber renders on every data change, not just the first one. The controller emits a new state on every get(). The wrong default is pre-selected. Read request.params.sort and the layers.default_sort_order metafield in Liquid, mark the matching <option> as selected server-side, and pass the same code as sort to the controller. Sort options are missing from the dropdown. Check Enable as Storefront Sort is on in the Layers dashboard and the metaobject’s scope array contains the right surface.

Liquid Integration

Liquid + Fetch guides

Liquid + SDK guides

Rendering sort orders with the SDK

Overview

Prerequisites

Fetching sort orders at runtime

Default sort orders

Why the SDK over Fetch

Troubleshooting

See also

​Overview

​Prerequisites

​Collection sort dropdown

​Search sort dropdown

​Fetching sort orders at runtime

​Combining sort with filters and pagination

​Default sort orders

​Why the SDK over Fetch

​Troubleshooting

​See also

Overview

Prerequisites

Collection sort dropdown

Search sort dropdown

Fetching sort orders at runtime

Combining sort with filters and pagination

Default sort orders

Why the SDK over Fetch

Troubleshooting

See also