Skip to main content

Reference · Event bus

The widget exposes two public channels on window:

  1. CustomEvent it emits — the host subscribes.
  2. CustomEvent it listens to — the host emits.

There is no public postMessage. The neuroon:setStyles / neuroon:setTheme / neuroon-preview-ready messages you see in widget/src/index-preact.tsx:114-161 are internal to the WordPress plugin admin preview and are not part of the integrator contract.

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(...).

  • Automatic dispatch: widget/src/index-preact.tsx:311 (prefers-color-scheme change).
  • Programmatic dispatch: widget/src/context/WidgetContext.tsx:846 (setTheme action).
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 widget listens at widget/src/context/CartContext.tsx:165-191 and, on receipt:

  1. Skips if widget-originated operations are in flight (avoids overwriting optimistic state).
  2. Applies a 300 ms debounce (some hosts fire several events in a row: added_to_cart, wc_fragments_refreshed).
  3. Calls config.cart.onGetCart() and updates its state.
// The listener ignores event.detail. Dispatch with no payload.
window.dispatchEvent(new CustomEvent('neuroon:cart-update'))

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

Example: WordPress / WooCommerce​

jQuery(document.body).on(
  'added_to_cart wc_fragments_refreshed removed_from_cart',
  () => window.dispatchEvent(new CustomEvent('neuroon:cart-update'))
)

The official WordPress plugin already wires this bridge automatically in its inline loader; see Plugins → WordPress → Cart bridge.

What the widget does not emit (you might expect it to)​

The following are configuration callbacks, not CustomEvents. Pass them in NeuroonWidgetConfig.callbacks:

CallbackTrigger
onSearch(query, results)after each successful search
onResultClick(product)click on a grid result
onFilterChange(filters)the user applies/removes filters
onError(error)error in any search phase

See Widget → Configuration for the full contract.

Further reading​

Last updated on