Listen for Widget State Changes with Custom Events

The Bird widget dispatches JavaScript custom events so you can react to what happens in it — update other page elements, track behavior, adjust pricing, or trigger integrations.

Two things to know:

• Selection and checkout events fire on window; widget-lifecycle events fire on document.
• All event data is on event.detail.

Upgrading from the old events? The previous widget used birdchime:initialized, birdchime:reinitialized, and birdchime:schedule. These map to bird:widget:initialized, bird:widget:reinitialized, and bird:selection:changed. The old events are documented under Legacy widget (V1) events below.

Events

Listen with addEventListener on the right target:

// selection + checkout events fire on window
window.addEventListener('bird:selection:changed', ({ detail }) => {
  console.log(detail.field, detail.value, detail.selection);
});

// lifecycle events fire on document
document.addEventListener('bird:widget:reinitialized', () => {
  // re-attach listeners / re-apply styling after an AJAX redraw
});

bird:selection:changed carries a compact detail.selection snapshot ({ method, locationId, zip, date, time }). For the full selection — location name, note, collector, SMS opt-in — read sdk.selections.current; see Widget APIs (REST & JavaScript).

Prefer a single subscription?

To receive every state change through one callback instead of several listeners, use sdk.subscribe(). It fires immediately with the current state, then on every change, and works on both Liquid and headless:

const sdk = await window.BirdApp.ready;
const unsubscribe = sdk.subscribe((state) => {
  console.log(state.selection, state.isComplete);
});

Headless storefronts

On headless storefronts only bird:selection:changed fires — the other events come from the Liquid theme integration. To know when checkout can proceed, use sdk.selections.canCheckout().canProceed, and use sdk.subscribe() for state changes.

Troubleshooting

Event not firing?

• Check the target — selection/checkout events are on window, lifecycle events on document. The wrong one silently receives nothing.
• Check the console for JavaScript errors.
• Attach listeners early, or inside bird:widget:initialized, so the widget is loaded first.
• Dynamic carts/sections re-mount the widget — handle bird:widget:reinitialized to re-attach anything that stopped working after an AJAX reload.

---

Legacy widget (V1) events

The events below apply only to the older (V1) widget, which dispatches birdchime:* events on document. If your store runs the current widget, use the bird:* events above instead — the birdchime:* events are not dispatched there.

birdchime:initialized

This event fires once, when the Bird Pickup & Delivery widget is fully loaded on the page for the first time.

Use this event to:

• Run setup logic
• Modify widget styling
• Load external dependencies
• Track widget impressions

document.addEventListener('birdchime:initialized', function({ detail }) {
  console.log('BirdChime widget initialized:', detail);
});

birdchime:reinitialized

This event fires whenever the widget is re-rendered or re-mounted automatically.

Common scenarios:

• AJAX carts / dynamic carousels
• Theme sections reloading
• Re-renders triggered by cart updates

Use this event to:

• Re-attach event listeners
• Re-apply custom styling
• Fix issues where custom JS stops working after AJAX reloads

document.addEventListener('birdchime:reinitialized', function({ detail }) {
  console.log('BirdChime widget reinitialized:', detail);
});

birdchime:schedule

This event fires any time the customer changes a selection, such as:

• Switches between Pickup, Delivery, or Shipping
• Chooses a date
• Selects a time slot

document.addEventListener('birdchime:schedule', function({ detail }) {
  console.log('Schedule event details:', detail);
});

Event data structure

Example data returned when the customer selects Local Delivery with a chosen date and time:

{
  "Delivery Method": "Delivery",
  "_BirdChimeSlotId": "M=D;L=105145;D=2025-11-26;T=9:00 AM - 6:00 PM;TS=2025-11-12 11:32:30;S=R;Z=",
  "locationId": 105145,
  "shopifyLocationId": 80424370330,
  "Delivery Date": "Nov 26, 2025",
  "Delivery Day": "Wednesday",
  "Delivery Time": "9:00 AM - 6:00 PM"
}

Related Articles

• Widget APIs (REST & JavaScript)
• How to Manually Add the Widget Code to Your Cart Page
• How to Expire Stale Delivery and Pickup Time Selections