Framework integration

The SDK’s reactive state is framework agnostic. Every controller exposes subscribe(callback), state, and dispose(). You can wrap these in a framework-specific hook, store, or effect. All examples below use a collection controller, but the same patterns apply to search, blocks, autocomplete, imageSearch, similarProducts, facets, sortOrders, searchContent, and createProductCard.

Vanilla JavaScript

Use subscribe to drive DOM updates directly:

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

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

  const grid = document.getElementById('product-grid')
  const loader = document.getElementById('loader')

  const unsubscribe = collection.subscribe(({ data, error, loading }) => {
    loader.hidden = !loading

    if (error) {
      grid.innerHTML = `<p>Error: ${error.message}</p>`
      return
    }

    if (data) {
      grid.innerHTML = data.products
        .map((p) => `<div class="product-card"><h3>${p.title}</h3></div>`)
        .join('')
    }
  })

  await collection.get()

  // Cleanup when done
  unsubscribe()
  collection.dispose()
}

React

Wrap controller.subscribe and controller.state in a hook using useSyncExternalStore:

import { useSyncExternalStore, useMemo, useEffect } from 'react'
import { getSDK, type Controller, type QueryState } from '@commerce-blocks/sdk'

function useControllerState<TData, TQuery = void>(
  createController: () => Controller<TData, TQuery>,
  deps: unknown[] = [],
): QueryState<TData> {
  const controller = useMemo(() => createController(), deps)

  useEffect(() => {
    return () => controller.dispose()
  }, [controller])

  return useSyncExternalStore(
    (onStoreChange) => controller.subscribe(() => onStoreChange()),
    () => controller.state,
    () => controller.state,
  )
}

Usage:

function CollectionGrid({ handle }: { handle: string }) {
  const { data: sdk, error: sdkError } = getSDK()

  if (sdkError) return <p>SDK error: {sdkError.message}</p>
  if (!sdk) return null

  const { data, error, loading } = useControllerState(
    () => sdk.collection({ collectionHandle: handle }),
    [handle],
  )

  if (loading) return <p>Loading...</p>
  if (error) return <p>Error: {error.message}</p>
  if (!data) return null

  return (
    <div className="product-grid">
      {data.products.map((product) => (
        <div key={product.id} className="product-card">
          <h3>{product.title}</h3>
        </div>
      ))}
    </div>
  )
}

Vue

Use Vue’s ref and onUnmounted to bridge SDK state:

<script setup lang="ts">
import { ref, onMounted, onUnmounted } from 'vue'
import { getSDK, type CollectionData, type QueryState } from '@commerce-blocks/sdk'

const props = defineProps<{ handle: string }>()

const products = ref<CollectionData | null>(null)
const error = ref<Error | null>(null)
const loading = ref(false)

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

const collection = sdk?.collection({ collectionHandle: props.handle })
let unsubscribe: (() => void) | undefined

onMounted(() => {
  if (!collection) return
  unsubscribe = collection.subscribe((state: QueryState<CollectionData>) => {
    products.value = state.data
    error.value = state.error
    loading.value = state.loading
  })
  collection.get()
})

onUnmounted(() => {
  unsubscribe?.()
  collection?.dispose()
})
</script>

<template>
  <p v-if="loading">Loading...</p>
  <p v-else-if="error">Error: {{ error.message }}</p>
  <div v-else-if="products" class="product-grid">
    <div v-for="product in products.products" :key="product.id" class="product-card">
      <h3>{{ product.title }}</h3>
    </div>
  </div>
</template>

Svelte

Use subscribe to drive Svelte’s reactive $state:

<script lang="ts">
  import { onDestroy } from 'svelte'
  import { getSDK, type CollectionData, type QueryState } from '@commerce-blocks/sdk'

  const { handle }: { handle: string } = $props()

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

  const collection = sdk?.collection({ collectionHandle: handle })
  let state = $state<QueryState<CollectionData> | null>(collection?.state ?? null)

  $effect(() => {
    if (!collection) return
    const unsubscribe = collection.subscribe((newState) => {
      state = newState
    })
    collection.get()
    return unsubscribe
  })

  onDestroy(() => {
    collection?.dispose()
  })
</script>

{#if state?.loading}
  <p>Loading...</p>
{:else if state?.error}
  <p>Error: {state.error.message}</p>
{:else if state?.data}
  <div class="product-grid">
    {#each state.data.products as product (product.id)}
      <div class="product-card">
        <h3>{product.title}</h3>
      </div>
    {/each}
  </div>
{/if}

Lit

Use subscribe in connectedCallback / disconnectedCallback:

import { LitElement, html } from 'lit'
import { customElement, property, state } from 'lit/decorators.js'
import { getSDK, type CollectionData, type Controller, type QueryState } from '@commerce-blocks/sdk'

@customElement('product-grid')
export class ProductGrid extends LitElement {
  @property() handle = ''

  @state() private products: CollectionData | null = null
  @state() private error: Error | null = null
  @state() private loading = false

  private controller?: Controller<CollectionData>
  private unsubscribe?: () => void

  connectedCallback() {
    super.connectedCallback()
    const { data: sdk, error: sdkError } = getSDK()
    if (sdkError || !sdk) return

    this.controller = sdk.collection({ collectionHandle: this.handle })

    this.unsubscribe = this.controller.subscribe((state: QueryState<CollectionData>) => {
      this.products = state.data
      this.error = state.error
      this.loading = state.loading
    })

    this.controller.get()
  }

  disconnectedCallback() {
    super.disconnectedCallback()
    this.unsubscribe?.()
    this.controller?.dispose()
  }

  render() {
    if (this.loading) return html`<p>Loading...</p>`
    if (this.error) return html`<p>Error: ${this.error.message}</p>`
    if (!this.products) return html``

    return html`
      <div class="product-grid">
        ${this.products.products.map(
          (product) => html`
            <div class="product-card">
              <h3>${product.title}</h3>
            </div>
          `,
        )}
      </div>
    `
  }
}

Alpine.js

Alpine pairs well with the SDK in zero-build Shopify themes. Boot the SDK from a CDN once, then use an Alpine component to expose controller state to your template. Hand the controller’s subscribe callback into Alpine’s reactive $data and the DOM updates automatically as the SDK state changes.

Boot the SDK once

Load the SDK and Alpine from a CDN, then create the SDK in a single <script type="module"> block in theme.liquid. See Loading from a CDN for alternative CDNs and version pinning.

<script src="//unpkg.com/alpinejs" defer></script>

<script type="module">
  import { createSDK } from 'https://unpkg.com/@commerce-blocks/sdk@3?module'

  const { error } = createSDK({
    storefrontAccessToken: '{{ shop.metafields.layers.embed_settings.value.storefrontApiToken }}',
    trackingToken: '{{ shop.metafields.layers.embed_settings.value.trackingToken }}',
    currencyCode: 'USD',
  })

  if (error) {
    console.error('SDK init failed:', error.message)
  }
</script>

Collection component

Define an Alpine component that owns a collection() controller. The init() lifecycle hook creates the controller, wires subscribe into Alpine’s reactive state, and triggers the initial get(). destroy() tears the subscription and the controller down so navigating away never leaks state.

<div
  x-data="layersCollection({ collectionHandle: 'shirts' })"
  x-init="init()"
  @destroy="destroy()"
>
  <template x-if="loading">
    <p>Loading...</p>
  </template>

  <template x-if="error">
    <p x-text="`Error: ${error.message}`"></p>
  </template>

  <ul class="product-grid">
    <template x-for="product in products" :key="product.id">
      <li class="product-card">
        <a :href="`/products/${product.handle}`">
          <h3 x-text="product.title"></h3>
          <span x-text="product.priceRange?.min?.formatted"></span>
        </a>
      </li>
    </template>
  </ul>

  <button @click="loadMore()" x-show="page < totalPages">Load more</button>
</div>

<script type="module">
  import { getSDK } from 'https://unpkg.com/@commerce-blocks/sdk@3?module'

  window.layersCollection = ({ collectionHandle }) => ({
    products: [],
    page: 1,
    totalPages: 1,
    loading: false,
    error: null,
    _controller: null,
    _unsubscribe: null,

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

      this._controller = sdk.collection({ collectionHandle })

      this._unsubscribe = this._controller.subscribe(({ data, error, loading }) => {
        this.loading = loading
        this.error = error

        if (data) {
          this.products = data.products
          this.page = data.page
          this.totalPages = data.totalPages
        }
      })

      this._controller.get()
    },

    loadMore() {
      this._controller.get({ pagination: { page: this.page + 1 } })
    },

    destroy() {
      this._unsubscribe?.()
      this._controller?.dispose()
    },
  })
</script>

The component reads data.products, data.page, and data.totalPages straight off the SDK state and exposes them as Alpine reactive properties. Every subscribe emit re-renders the matching x-text, x-for, and x-show bindings.

Search component

The same pattern works for search. Create a new search controller when the shopper submits a query, and use autocomplete() for suggestions.

<div x-data="layersSearch()" x-init="init()" @destroy="destroy()">
  <input
    type="search"
    x-model="query"
    @input="suggest()"
    placeholder="Search..."
  />

  <ul x-show="suggestions.length" class="suggestions">
    <template x-for="s in suggestions" :key="s.query_text">
      <li>
        <a :href="`/search?q=${encodeURIComponent(s.query_text)}`" x-text="s.query_text"></a>
      </li>
    </template>
  </ul>
</div>

<script type="module">
  import { getSDK } from 'https://unpkg.com/@commerce-blocks/sdk@3?module'

  window.layersSearch = () => ({
    query: '',
    suggestions: [],
    _autocomplete: null,
    _unsubscribe: null,

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

      this._autocomplete = sdk.autocomplete()

      this._unsubscribe = this._autocomplete.subscribe(({ data, error }) => {
        if (error) {
          console.error('Autocomplete failed:', error.message)
          return
        }
        if (data?._meta?.redirect?.url) {
          window.location.href = data._meta.redirect.url
          return
        }
        this.suggestions = data?.matchedQueries ?? []
      })
    },

    suggest() {
      const q = this.query.trim()
      if (!q) {
        this.suggestions = []
        return
      }
      this._autocomplete.get({ query: q })
    },

    destroy() {
      this._unsubscribe?.()
      this._autocomplete?.dispose()
    },
  })
</script>

For production, debounce the @input handler so you do not fire an autocomplete request on every keystroke.

ProductCard integration

The createProductCard controller follows the same patterns. Here is a React example:

import { useSyncExternalStore, useMemo, useEffect, useRef } from 'react'
import { createProductCard, type Product, type ProductCardState } from '@commerce-blocks/sdk'

function useProductCardState(card: ReturnType<typeof createProductCard>): ProductCardState {
  return useSyncExternalStore(
    (onStoreChange) => card.subscribe(() => onStoreChange()),
    () => card.state,
    () => card.state,
  )
}

function ProductCard({ product }: { product: Product }) {
  const card = useMemo(() => createProductCard({ product }), [product])

  useEffect(() => {
    return () => card.dispose()
  }, [card])

  const state = useProductCardState(card)

  return (
    <div>
      <h3>{product.title}</h3>
      {state.options.map((group) => (
        <div key={group.name}>
          <label>{group.name}</label>
          {group.values.map((opt) => (
            <button
              key={opt.value}
              disabled={opt.status === 'unavailable'}
              data-selected={opt.selected}
              onClick={() => card.selectOption({ name: group.name, value: opt.value })}
            >
              {opt.value}
              {opt.status === 'sold-out' && ' (Sold out)'}
            </button>
          ))}
        </div>
      ))}
      {state.price.price && <p>{state.price.price.formatted}</p>}
    </div>
  )
}

The SDK exports a subscribe utility that works with any controller:

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

const collection = sdk.collection({ collectionHandle: 'shirts' })

const unsubscribe = subscribe(collection, ({ data, error, loading }) => {
  if (loading) console.log('Loading...')
  if (error) console.error('Error:', error.message)
  if (data) console.log('Products:', data.products)
})

Overview

SDK Reference

SDK Guides

Changelog & Upgrades

AI Enablement

Framework integration

Vanilla JavaScript

React

Vue

Svelte

Lit

Alpine.js

Boot the SDK once

Collection component

Search component

ProductCard integration

Next steps

​Vanilla JavaScript

​React

​Vue

​Svelte

​Lit

​Alpine.js

​Boot the SDK once

​Collection component

​Search component

​ProductCard integration

​Using standalone subscribe

​Next steps

Vanilla JavaScript

React

Vue

Svelte

Lit

Alpine.js

Boot the SDK once

Collection component

Search component

ProductCard integration

Using standalone `subscribe`

Next steps