--- title: "Developer Javascript and events" description: "Some events we emit so you can build additional logic around them" url: https://help.biscuitsbundles.com/en/articles/9045771-developer-javascript-and-events collection: "Developer Documentation" updated: 2026-10-01 language: en --- # Developer Javascript and events Some events we emit so you can build additional logic around them Biscuits Bundles components communicate through standard DOM `CustomEvent`s 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.

Event

Fired by

BiscuitsBundleForm:ready

<biscuits-bundle-form>

BiscuitsBundleStep:ready

<biscuits-bundle-step>

BiscuitsBundleVariant:ready

<biscuits-bundle-variant>

BiscuitsBundleProduct:ready

<biscuits-bundle-product>

BiscuitsBundleQuantity:ready

<biscuits-bundle-quantity>

BiscuitsBundlePrice:ready

<biscuits-bundle-price>

BiscuitsBundleSummary:ready

<biscuits-bundle-summary>

BiscuitsBundleAddToCart:ready

<biscuits-bundle-add-to-cart>

BiscuitsBundleAccordionSummary:ready

<biscuits-bundle-accordion-summary>

BiscuitsBundleVolumeDiscounts:ready

<biscuits-bundle-volume-discounts>

BiscuitsBundleVolumeDiscountTier:ready

<biscuits-bundle-volume-discount-tier>

BiscuitsBundleRelatedBundles:ready

<biscuits-bundle-related-bundles>

BiscuitsBundleCustomFieldGroup:ready

<biscuits-bundle-custom-field-group>

## App-level event

Event

Fired on

When

BiscuitsBundle:allReady

the <biscuits-bundle-form> element and document

After every sub-component is ready and the bundle has finished its first render. This is the safe entry point for custom code.

## Interaction events

Event

detail payload

When

biscuits--product-selection

{ variant_id, price, compare_at_price, quantity, active, max, step, product_id, uniqueCode, product_title, variant_title, quantity_available }

A product/variant is selected or deselected. product_id is only present for multi-variant products.

biscuits--quantity-updated

{ quantity, fixedQuantity }

A quantity control value changes and passes validation.

biscuits--step-update

{ stepIndex, selectedProducts, totalQuantity, totalSelected, totalPrice, comparePrice, valid, required, maxSelectedReached, maxQuantityReached, minSelectedReached, minQuantityReached }

A step's totals/validation change after a selection or quantity change. The primary event to listen to for reacting to selections. Does not fire for custom-field changes.

biscuits--custom-field-change

none

A custom field's value changes. Read current values from the field elements (it's a signal, not a snapshot).

biscuits--accordion-advance

{ stepIndex }

The accordion auto-advances to the next incomplete step. stepIndex is the step that was opened.

biscuits--add-to-cart-success

{ data } — Shopify's cart/add.js response

The bundle was added successfully, before any theme cart drawer/refresh runs.

biscuits--add-to-cart-error

{ status, message, error }

The add-to-cart request failed (non-2xx response or network error). Does not fire on client-side validation errors.

## The `window.BiscuitsBundle` global Useful properties and helpers available at runtime:

Property

Description

formatMoney(cents, format)

Formats a cents integer into a localised money string.

moneyFormat / moneyFormatTotal

The shop's money format strings.

translations

All app language strings, keyed by translation key.

routes

{ cartAddUrl, cartUrl } Shopify route helpers.

bundleStepScrollOffset / bundleSummaryScrollOffset

Pixel offsets for auto-scroll (default 200). Override before init.

disableAccordionScroll

Set true to disable accordion auto-scrolling.

themeDataOverride / themeDataDefault

Control post-add-to-cart cart drawer/redirect behaviour.

## 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](https://help.biscuitsbundles.com/en/articles/14043181-localised-bundles-pricing-for-shopify-markets.md). ## Common code blocks **Run code after the bundle is ready** ```javascript 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** ```javascript 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 // event.detail.totalPrice, event.detail.valid, etc. }); }); }); ``` **React to a successful add-to-cart** ```javascript 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** ```javascript 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. ```javascript ``` 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 [hello@sundaelane.com](mailto:hello@sundaelane.com) Happy coding, and thanks for teaming up with Biscuits Bundles!