Configure the widget | Subbly Developers

SubblyCart.js widget

window.subblyConfig takes a dozen keys. Five of them cover most first integrations:

apiKey: your Storefront API key. The only required key.
languageCode: a two-letter language. Without it, the widget takes the lang query parameter, then the lang attribute of <html>, then the browser's language.
settings: the page hooks — which links the widget catches, which element opens it, which element shows the item count. See Wire it into your page.
init: set it to false to boot the widget yourself.
checkoutUrl: a page on your site that owns the checkout. The widget sends the customer there and stands down on that path.

A typical config
<script>
  window.subblyConfig = {
    apiKey: 'YOUR_STOREFRONT_API_KEY',
    languageCode: 'fr',
    settings: {
      interceptProductLinks: true,
      cartToggleEl: '.js-cart-toggle',
      cartCounterEl: '.js-cart-count'
    },
    checkoutUrl: '/checkout'
  }
</script>

With init: false, the loader sets no global. Call SubblyCart.initialize yourself and keep the instance it returns:


Boot the widget by hand
window.subblyConfig = { init: false }

window.addEventListener('subbly-cart-loaded', async () => {
  const cart = await window.SubblyCart.initialize({
    apiKey: 'YOUR_STOREFRONT_API_KEY'
  })

  cart.events.on(cart.events.type.CART_UPDATED, () => {
    console.log('cart changed')
  })
})

Every key, with its type and default, is on Configuration keys. SubblyCart.initialize(config) takes the same object, and you can change the URL keys later with configure.

Last modified on September 14, 2026

SubblyCart.js widget

window.subblyConfig takes a dozen keys. Five of them cover most first integrations:

apiKey: your Storefront API key. The only required key.
languageCode: a two-letter language. Without it, the widget takes the lang query parameter, then the lang attribute of <html>, then the browser's language.
settings: the page hooks — which links the widget catches, which element opens it, which element shows the item count. See Wire it into your page.
init: set it to false to boot the widget yourself.
checkoutUrl: a page on your site that owns the checkout. The widget sends the customer there and stands down on that path.

A typical config
<script>
  window.subblyConfig = {
    apiKey: 'YOUR_STOREFRONT_API_KEY',
    languageCode: 'fr',
    settings: {
      interceptProductLinks: true,
      cartToggleEl: '.js-cart-toggle',
      cartCounterEl: '.js-cart-count'
    },
    checkoutUrl: '/checkout'
  }
</script>

With init: false, the loader sets no global. Call SubblyCart.initialize yourself and keep the instance it returns:


Boot the widget by hand
window.subblyConfig = { init: false }

window.addEventListener('subbly-cart-loaded', async () => {
  const cart = await window.SubblyCart.initialize({
    apiKey: 'YOUR_STOREFRONT_API_KEY'
  })

  cart.events.on(cart.events.type.CART_UPDATED, () => {
    console.log('cart changed')
  })
})

Every key, with its type and default, is on Configuration keys. SubblyCart.initialize(config) takes the same object, and you can change the URL keys later with configure.

Last modified on September 14, 2026