Widget events

The widget does not expose public JavaScript callbacks to react to searches or clicks; instead, it exposes three channels:

1. CustomEvents emitted on window for the host to subscribe to.
2. CustomEvents listened to on window, that the host can emit to feed the widget.
3. postMessage inbound for iframe environments (WordPress admin, previews).

All the logic is concentrated.

Emitted events

Event	Dispatcher	Detail	When it fires
neuroon-theme-change	window.dispatchEvent	{ theme: 'light' | 'dark', containerId: string }	Theme changes (OS auto-detect or explicit call).
neuroon-preview-ready	window.parent.postMessage	{ type: 'neuroon-preview-ready', containerId }	The widget is embedded in an iframe (admin previews). Only sent when window.parent !== window.

Example: react to theme change

window.addEventListener('neuroon-theme-change', (e) => {
  console.log('Widget switched to theme', e.detail.theme, 'in', e.detail.containerId)
  // E.g. sync your store header theme
  document.documentElement.dataset.theme = e.detail.theme
})

Listened events (host → widget)

Event	Where it is dispatched	Detail / payload	Action
neuroon:cart-update	window.dispatchEvent from the host (WP, Shopify, custom)	CustomEvent (no detail; the handler reads the cart via cart.onGetCart)	The widget calls config.cart.onGetCart, debounced 300 ms, unless widget-originated operations are in flight.

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

Example: refresh the widget after add-to-cart in 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.

Inbound postMessage

The widget listens for message on window and processes events whose data.type starts with neuroon: or neuroon-. This is meant for an admin panel embedded in an iframe to control the widget in preview.

data.type	Additional payload	Action
neuroon:setStyles	{ styles: StyleOverrides | ThemedStyleOverrides; theme?: 'light' | 'dark' }	Re-injects styles into the Shadow DOM.
neuroon-styles-update	(legacy alias of neuroon:setStyles for WP preview compatibility)	same
neuroon:setTheme	{ theme: 'light' | 'dark' | 'auto' }	Changes the active theme on all instances or, if containerId is provided, only on one.

Security

• Messages with event.origin === 'null' (sandboxed iframes) are rejected.
• Only recognized neuroon:* or neuroon-* types are processed. The rest are silently ignored.
• Messages may include an optional containerId to target a specific instance. If omitted, it applies to all instances.

Example: change theme from an admin iframe

// Inside the admin iframe
window.parent.document.querySelector('iframe.neuroon-preview')
  .contentWindow.postMessage({
    type: 'neuroon:setTheme',
    theme: 'dark',
    containerId: 'neuroon-search',
  }, '*')

Full snippet: listener from the host

<script>
  // Theme
  window.addEventListener('neuroon-theme-change', (e) => {
    console.log('[host] theme:', e.detail.theme)
  })

  // Your host emits cart-update after any cart mutation
  function notifyNeuroonCart() {
    window.dispatchEvent(new CustomEvent('neuroon:cart-update'))
  }

  // Hook for your platform:
  // - WooCommerce: jQuery(document.body).on('added_to_cart …', notifyNeuroonCart)
  // - Shopify Liquid: window.addEventListener('cart:updated', notifyNeuroonCart)
  // - Custom: call after your own cart mutation
</script>

What does the widget not expose?

The widget does not expose public callbacks for search, result-click, filter-change, conversion or error. The only public callbacks are for Widget Token rotation (onTokenExpiring, onTokenRefreshed).

If you need to measure product clicks or other search activity, the widget reports tracking to the backend automatically; you query the metrics through the Dashboard. There is no JavaScript extension point.

Further reading

• Reference → Event bus — exhaustive table with payload schemas.
• Cart integration — full cart-update bridge flow.
• Theming — using setTheme/setStyles from the host.