Developer Javascript and events

Biscuits Bundles components communicate through standard DOM CustomEvents and expose runtime configuration on the global window.BiscuitsBundle object. This page lists every event you can listen for and the most useful global hooks.

Ready events

Each component fires a one-time :ready event when it finishes initialising. All bubble and carry no detail payload.

App-level event

Interaction events

The window.BiscuitsBundle global

Useful properties and helpers available at runtime:

Localised bundles

All events on this page fire for localised bundles too, including biscuits--add-to-cart-success. The add to cart request itself is different though: a localised bundle adds its component lines with their own properties (_bundleId, _selectedItems, _biscuitsDisplayTitle), so the cart/add.js response in event.detail.data and the resulting cart contents have a different shape. Custom code that reads the cart response, or matches lines by properties like _biscuits_title, should be tested against a localised bundle. _bundleId is carried on every bundle line for both kinds, so it is the reliable way to identify bundle lines. See Localised bundles: pricing for Shopify Markets.

Common code blocks

Run code after the bundle is ready

const form = document.querySelector('biscuits-bundle-form');
form.addEventListener('BiscuitsBundle:allReady', () => {
  // All components are initialised — safe to read form.formTotalPrice, etc.
});

💡 Tip: Make sure you don't put this event listener inside a "DOMContentLoaded" as our ready events will trigger before this.

React to selection changes

const form = document.querySelector('biscuits-bundle-form');
form.addEventListener('BiscuitsBundle:allReady', () => {
  form.querySelectorAll('biscuits-bundle-step').forEach((step) => {
    step.addEventListener('biscuits--step-update', (event) => {
      // event.target is the <biscuits-bundle-step>
      // event.detail.totalPrice, event.detail.valid, etc.
    });
  });
});

React to a successful add-to-cart

const addToCart = document.querySelector('biscuits-bundle-add-to-cart');
addToCart.addEventListener('biscuits--add-to-cart-success', (event) => {
  const cartResponse = event.detail.data; // Shopify cart/add.js response
});

Read the current total

const form = document.querySelector('biscuits-bundle-form');
form.addEventListener('BiscuitsBundle:allReady', () => {
  form.querySelectorAll('biscuits-bundle-step').forEach((step) => {
    step.addEventListener('biscuits--step-update', () => {
      const totalCents = form.formTotalPrice;
      const formatted = window.BiscuitsBundle.formatMoney(totalCents, window.BiscuitsBundle.moneyFormat);
      // formatted holds the current total (after discounts), in the shop's money format
    });
  });
});

Where does your custom code output?

When using the Custom JS field in the Biscuits Bundles app block, your custom javascript code is placed at the very bottom of our Shopify theme block code. This ensures that you can use event listeners on our custom events and interact with fully loaded DOM elements.

<!-- our Biscuits Bundles code -->

<script>
/* Your custom javascript will output here */
</script>

<script src="biscuits-section-bundle-production.min.js" defer></script>

Some of the other values you could access on the form are:

• formCompareAtPrice

• formDiscountValue

• formSavingsAmount

• formSavingsPercentage

• formTotalPrice

Testing

Always thoroughly test your custom JS to ensure if behaves as expected across all supported browsers and devices.

Stuck or got questions?

Use the chat widget below, or reach out to us at [email protected]

Happy coding, and thanks for teaming up with Biscuits Bundles!