Events

Events let you run custom code when something happens — for example, when a visitor adds an add-on or when prices update. This is an advanced feature; most setups do not need custom event handling.

toggle:toggled

When: A card is clicked and the cart operation completes (either add or remove).

Payload:

toggle:selection-changed

When: After every cart sync — on page load and whenever the cart changes.

Payload:

toggle:price-updated

When: After price data is fetched and applied to a card — on page load, after cart changes, after currency or coupon changes.

Payload:

This event is used internally by the external display system (data-next-display="toggle.{packageId}.{property}") to update bound elements. You can also listen to it to react to price updates for a specific card.

upsell:added

When: A card inside a data-next-upsell-context container is clicked and the upsell is successfully added to the order.

Payload:

After this event, the page navigates to the URL specified by data-next-url on the card (or the <meta name="next-upsell-url"> fallback).

Listening to Events

To listen to these events, paste the following code into a <script> tag at the bottom of your page. The code runs after the page is ready.

window.nextReady.push(() => {
  window.next.on('toggle:toggled', ({ packageId, added }) => {
    console.log(added ? 'Added:' : 'Removed:', packageId);
  });

  window.next.on('toggle:selection-changed', ({ selected }) => {
    console.log('Active packages:', selected);
  });
});

Example: Track add-on selections in analytics

window.nextReady.push(() => {
  window.next.on('toggle:toggled', ({ packageId, added }) => {
    // Send to Google Analytics
    gtag('event', added ? 'addon_added' : 'addon_removed', {
      package_id: packageId
    });
  });
});