Skip to main content

Reference · Event bus

The widget communicates with the host via two public channels on window:

  1. CustomEvents emitted — the host subscribes.
  2. CustomEvents listened to — the host emits.

There is no public postMessage for external integrators.

Summary​

TypeDirectionNamePayload
CustomEventwidget → hostneuroon-theme-change{ theme: 'light' | 'dark', containerId?: string }
CustomEventhost → widgetneuroon:cart-update(no detail)

neuroon-theme-change (widget → host)​

Fired when the active theme changes, either because the system changed under theme="auto" or because the host called widget.setTheme(...).

type NeuroonThemeChangeDetail = {
  theme: 'light' | 'dark'
  containerId?: string  // only present on automatic system-triggered changes
}

window.addEventListener('neuroon-theme-change', (e) => {
  const {theme, containerId} = (e as CustomEvent<NeuroonThemeChangeDetail>).detail
  document.documentElement.dataset.theme = theme
  // If you have multiple widget instances, filter by containerId.
})

neuroon:cart-update (host → widget)​

The host emits it after any cart mutation outside the widget (mini-cart, cart page, another plugin). The listener ignores event.detail — on receipt the widget calls config.cart.onGetCart() to read the cart from your host.

// The listener ignores event.detail. Dispatch with no payload.
window.dispatchEvent(new CustomEvent('neuroon:cart-update'))

Behavior:

  1. If widget-originated operations are in flight, the event is discarded (no overwriting of optimistic state).
  2. Debounced 300 ms.
  3. Calls config.cart.onGetCart() and updates internal state.

The event name is configurable via cart.externalUpdateEvent (default 'neuroon:cart-update').

Reacting to searches, clicks or conversions​

Subscribe to the DOM events listed above or consume the server-side tracking endpoint. For advanced flows, the onTokenExpiring / onTokenRefreshed callbacks in NeuroonWidgetConfig.callbacks let you orchestrate token rotation from the host.

Further reading​

Last updated on