Scripting the elements

The elements cover the common storefront with markup alone. When you need more, everything they use is reachable from script: the client, the shared cart store and a qb: event for everything that happens.

`window.Quickbutik`

The script-tag build exposes the whole kit as window.Quickbutik:

// The ambient shop
Quickbutik.shop          // { client, cartStore, currency, locale, analytics } | null
Quickbutik.client        // the SDK client; assignable, to swap in your own
Quickbutik.cart          // the shared CartStore
Quickbutik.clearCart()   // empty the basket; every <qb-cart> / <qb-cart-count> updates
Quickbutik.configure({ publishableKey: "qb_pk_…", currency: "EUR", storefrontId: "sf_…" })

// Currencies (see /kit/concepts/currencies)
Quickbutik.currency                    // "EUR", or null for the shop's own
Quickbutik.setCurrency("NOK")          // reprice the page; remembered. null = back to the default
Quickbutik.onCurrencyChange((code) => …)   // returns an unsubscribe
Quickbutik.describeCurrency(shop, "NOK")   // { currency, mode, chargeCurrency, … }

// Consent and analytics (see /kit/concepts/consent-and-analytics)
Quickbutik.consent       // the page's ConsentStore: allows(), acceptAll(), reset(), openSettings(), …
Quickbutik.analytics     // the analytics hub, or null with analytics or consent off
Quickbutik.track({ name: "view_item_list", params: { item_list_name: "Nyheter", items } })
Quickbutik.trackPurchase(purchase, { orderNumber })

// Setup
Quickbutik.defineElements({ prefix: "shop-" })
Quickbutik.elementConstructors
Quickbutik.defined       // what was registered on load, or null
Quickbutik.error         // a malformed data-publishable-key, if there was one
Quickbutik.version

// The SDK, for anything the elements do not cover
Quickbutik.createShopkitClient({ … })
Quickbutik.ShopkitApiError   // …and the rest of the error classes

// Framework-free helpers
Quickbutik.formatMoney(129900, "SEK", { locale: "sv-SE" })   // "1 299,00 kr"
Quickbutik.formatMoneyRange(9900, 99900, "SEK")
Quickbutik.buildSeo({ product, baseUrl: "https://minbutik.se" })
Quickbutik.resolveProductImageUrl(image, { width: 400 })
Quickbutik.CartStore, Quickbutik.ProductController, Quickbutik.AsyncResource

With a bundler, the same pieces are imports: configure() (returns { client, cartStore }) and getAmbientShop() come from @quickbutik/kit/elements; formatMoney, buildSeo, the image helpers, ProductController and AsyncResource come from @quickbutik/kit. Quickbutik.client is the full SDK client, so anything the elements do not do is a plain call:

const { data } = await Quickbutik.client.products.search({ search: "merino", limit: 10 })

The cart store

Quickbutik.cart (or configure().cartStore) is the one store every cart element reads.

Member
`subscribe(fn)`	Called on every change. Returns an unsubscribe
`getSnapshot()`	`{ cart, status, pending, error, itemCount }`
`load()`	Read the remembered cart. Never creates one
`refresh()`	Re-read the cart
`add(item)`	Create the cart on first use, add, recover once from a stale cookie
`updateItem(itemId, quantity)`	`itemId` is the line id. `0` removes
`removeItem(itemId)`
`clear()`	Delete the remembered cart and forget it
`hydrate(cart)`	Adopt a cart fetched elsewhere

Mutations capture errors into error and resolve to null instead of throwing.

Use this store rather than a second client for cart work. A second client keeps its own state, so your code and the elements disagree until the next reload.

Events

Every element emits qb:-prefixed events that bubble and compose, so one listener on the document catches all of them.

Event	Emitted by	`detail`
`qb:shop-ready`	`qb-shop`	`{ client, cartStore, currency, locale }`
`qb:product-change`	`qb-product`	`{ product }`
`qb:variant-change`	`qb-product`	`{ variant }`
`qb:added-to-cart`	`qb-product`	`{ cart, quantity }`
`qb:add-to-cart-blocked`	`qb-product`	`{ missingOptions }`, the groups still missing a choice (for a blocked buy-now too)
`qb:product-not-found`	`qb-product`	`{ slug, productId }`
`qb:added`	`qb-add-to-cart`	`{ cart, quantity }`
`qb:products`	`qb-product-list`	`{ products }`
`qb:checkout-started`	`qb-checkout-button`, `qb-buy-now`, `qb-product` (buy-now)	The start result: `url`, `checkout` (`"v2"` or `"legacy"`), `handoffId`, `cartId`, plus `session` on v2
`qb:checkout-empty`	`qb-checkout-button`, `qb-checkout`	`{}`
`qb:checkout-ready`	`qb-checkout`	`{ sessionId, shopId, step }`
`qb:checkout-step`	`qb-checkout`	`{ step }`: `"contact"` or `"payment"`
`qb:checkout-event`	`qb-checkout`	`{ name, params }`, GA4-shaped commerce events
`qb:checkout-complete`	`qb-checkout`	`{ sessionId, orderNumber, successUrl }`
`qb:checkout-fallback`	`qb-checkout`	`{ reason, url }`. Reasons: `legacy`, `no-embed-url`, `no-top-navigation`, `handshake-timeout`
`qb:checkout-error`	`qb-checkout`	`{ code, message, fatal }`
`qb:confirmation`	`qb-order-confirmation`	The poll outcome
`qb:seo`	`qb-seo`	The `SeoTags` it wrote
`qb:currency-change`	`qb-currency-select`	`{ currency }` after a choice
`qb:consent`	`document`	The consent state, on every decision
`qb:error`	any	`{ error, context }`

<script>
  addEventListener("qb:added-to-cart", (e) => {
    openDrawer()
    console.log("added", e.detail.quantity)
  })
  addEventListener("qb:add-to-cart-blocked", (e) => {
    showHint(`Välj ${e.detail.missingOptions[0].name}`)
  })
  addEventListener("qb:error", (e) => console.warn(e.detail.context, e.detail.error))
</script>

Errors are mostly silent

Elements report failures as state rather than exceptions:

A failed product lookup sets state="error" on <qb-product>; no event, no console line.
A failed list sets state="error" and list.error.
A failed cart mutation is captured by the store: add() resolves null, none of qb:added, qb:added-to-cart or qb:error fires, the cart elements reflect state="error", and the message is in Quickbutik.cart.getSnapshot().error (not in the cart.* scope).
qb:error fires for startup failures (no shop, a bad key), a <qb-shop> that cannot build its client, a checkout that fails to start and a confirmation that cannot run.

Style [state="error"] and read the store when you need the message:

Quickbutik.cart.subscribe(() => {
  const { error } = Quickbutik.cart.getSnapshot()
  document.getElementById("cart-error").textContent = error ? error.message : ""
})

Recipes

A key from a server-rendered template

When the key is a template variable rather than a literal, load the library without auto-registration and configure it yourself:

<script defer src="https://cdn.jsdelivr.net/npm/@quickbutik/kit@1.8.0/dist/quickbutik-kit.global.js" data-no-auto-define></script>
<script type="module">
  Quickbutik.configure({
    publishableKey: window.SHOP_CONFIG.publishableKey,
    currency: window.SHOP_CONFIG.currency,
  })
  Quickbutik.defineElements()
</script>

type="module" matters. defer is ignored on an inline script, which would then run during parsing, before the deferred kit script has defined window.Quickbutik (Quickbutik is not defined). A module script runs after the deferred scripts before it, in order. Wrapping the code in a DOMContentLoaded listener also works.

Your own cart badge

<span id="badge">0</span>
<script type="module">
  const badge = document.getElementById("badge")
  Quickbutik.cart.subscribe(() => {
    const { itemCount, pending } = Quickbutik.cart.getSnapshot()
    badge.textContent = pending ? "…" : String(itemCount)
  })
  Quickbutik.cart.load()
</script>

Load more

Setting cursor on <qb-product-list> replaces the page. To append instead, bind the list’s next cursor into the markup, then fetch the following pages with the SDK and render the cards yourself:

<!-- sort-by puts the list on the search endpoint, so its cursor fits products.search() -->
<qb-product-list class="grid" limit="24" sort-by="createdAt">
  <template>…</template>
  <!-- outside the rows, list.* is in scope -->
  <span id="cursor" hidden data-qb-attr="data-next:list.nextCursor"></span>
</qb-product-list>
<div id="more-results" class="grid"></div>
<button id="more" type="button">Visa fler</button>

<script type="module">
  const list = document.querySelector("qb-product-list")
  const target = document.getElementById("more-results")
  let cursor = null

  // A new first page (a new search term): start over.
  list.addEventListener("qb:products", () => {
    cursor = null
    target.replaceChildren()
  })

  document.getElementById("more").addEventListener("click", async () => {
    cursor ??= document.getElementById("cursor").dataset.next ?? null
    if (!cursor) return
    const page = await Quickbutik.client.products.search({
      search: list.getAttribute("search") || undefined,
      sortBy: "createdAt",
      limit: 24,
      cursor,
    })
    cursor = page.next_cursor
    for (const product of page.data) {
      const src = Quickbutik.resolveProductImageUrl(Quickbutik.pickProductImage(product), { width: 400 })
      const card = document.createElement("a")
      card.className = "card"
      card.href = `/products/${encodeURIComponent(product.slug ?? product.id)}`
      card.innerHTML = src ? `<img src="${src}" alt="" width="400" height="400" loading="lazy">` : ""
      const name = document.createElement("h3")
      name.textContent = product.name ?? ""   // textContent: merchant data is never trusted as HTML
      card.append(name)
      target.append(card)
    }
    document.getElementById("more").hidden = !page.has_more
  })
</script>

A custom picker

document.querySelector("qb-product").selection is the live ProductController. Drive it from any UI and the element re-renders on every change:

const product = document.querySelector("qb-product")
const controller = product.selection

controller.select(optionId, valueId)   // repairs contradictions, like a click
controller.clear(optionId)
controller.reset()
controller.selectVariant(variantId)

controller.subscribe(() => {
  const { selectedVariant, isComplete, price } = controller.getSnapshot()
  console.log(isComplete, selectedVariant?.sku, price.amount)
})

Clear the cart

<button id="empty-cart" type="button">Töm varukorgen</button>
<script type="module">
  document.getElementById("empty-cart").addEventListener("click", () => Quickbutik.clearCart())
</script>

Inside a <qb-cart>, <button data-qb-action="clear-cart"> does the same with no script.

Your own currency links

<nav>
  <a href="#" data-currency="SEK">SEK</a>
  <a href="#" data-currency="EUR">EUR</a>
</nav>
<script type="module">
  document.querySelectorAll("[data-currency]").forEach((link) =>
    link.addEventListener("click", (event) => {
      event.preventDefault()
      Quickbutik.setCurrency(link.dataset.currency)   // every product, list and cart element reprices
    }),
  )
  Quickbutik.onCurrencyChange((code) => console.log("now browsing in", code))
</script>

<qb-currency-select> with a <template> does the same in markup, and lists only the currencies the shop actually offers. See Currencies.

Navigate to the checkout yourself

no-redirect stops the navigation and hands you the URL, for example to pass an explicit cart id inside an app builder’s preview, where cookies are blocked:

<qb-checkout-button no-redirect><button type="button">Till kassan</button></qb-checkout-button>

<script type="module">
  addEventListener("qb:checkout-started", (e) => location.assign(e.detail.url))
</script>

Or skip the element and start the checkout with the SDK:

const { url } = await Quickbutik.client.checkout.start({
  cartId: Quickbutik.cart.getSnapshot().cart?.id,
  successUrl: `${location.origin}/success`,
  backUrl: location.origin,
  language: "sv",
})
location.assign(url)

Content Security Policy

The bundle evaluates no strings (no eval, no new Function). With analytics off (data-analytics="false") it loads nothing else on its own, so this is the whole policy it needs:

script-src  'self' https://cdn.jsdelivr.net
connect-src https://commerce.quickbutik.com
img-src     https://cdn.quickbutik.com
frame-src   https://pay.quickbutik.com    # only with <qb-checkout>

With analytics on (the default), it loads the merchant’s own vendors once the shopper consents, and the policy must allow them as well:

script-src  https://www.googletagmanager.com https://connect.facebook.net
connect-src https://www.google-analytics.com https://*.analytics.google.com https://www.facebook.com
img-src     https://www.facebook.com https://www.google-analytics.com

Every tag it adds is async and carries data-qb-analytics.

Getting Started

Vanilla JavaScript

React

Web Components

Concepts

API Reference

`window.Quickbutik`

The cart store

Events

Errors are mostly silent

Recipes

A key from a server-rendered template

Your own cart badge

Load more

A custom picker

Clear the cart

Your own currency links

Navigate to the checkout yourself

Content Security Policy

​window.Quickbutik

​The cart store

​Events

​Errors are mostly silent

​Recipes

​A key from a server-rendered template

​Your own cart badge

​Load more

​A custom picker

​Clear the cart

​Your own currency links

​Navigate to the checkout yourself

​Content Security Policy

`window.Quickbutik`

The cart store

Events

Errors are mostly silent

Recipes

A key from a server-rendered template

Your own cart badge

Load more

A custom picker

Clear the cart

Your own currency links

Navigate to the checkout yourself

Content Security Policy