Skip to main content

Widget configuration

The widget accepts configuration through two paths:

  1. data-* attributes on the <script> when using auto-init — the supported way for server-rendered templates (WordPress, ASP.NET, PHP, etc.).
  2. NeuroonWidgetConfig via the JavaScript API window.NeuroonWidget.init(config) when you need callbacks, cart integration or programmatic control.

Both paths produce the same instance. If you pass both, what arrives via init(config) takes precedence over the data-* attributes.

data-* attributes​

AttributeRequiredDefaultNotes
data-tokenyes—24 h Widget Token signed by your server with the Shop API Key (HMAC).
data-containerno#neuroon-searchCSS selector or container id.
data-themenoautoauto | light | dark. When auto, prefers-color-scheme is evaluated and tracked on change.
data-localenoautodetect (fallback es)Valid codes: es, en, fr, de, it, pt, ca, eu, gl.
data-api-urlnohttps://api.neuroon.aiAPI base URL override. Switch to Development with https://dev-api.neuroon.ai.
data-placeholderno(i18n string)Empty-input text.
data-suggestionsnotruefalse disables the suggestions dropdown.
data-filtersnotruefalse disables filters and the drawer.
data-primary-colorno(theme default)Hex/rgb of the primary color (legacy; prefer StyleOverrides).

The attribute parser silently ignores any data-* attribute not listed above.

NeuroonWidgetConfig​

interface NeuroonWidgetConfig {
  container: string | HTMLElement
  token: string
  apiUrl?: string
  theme?: 'auto' | 'light' | 'dark'
  locale?: 'es' | 'en' | 'fr' | 'de' | 'it' | 'pt' | 'ca' | 'eu' | 'gl'
  translations?: Partial<Translations>
  styles?: StyleOverrides | { light?: StyleOverrides; dark?: StyleOverrides }
  features?: FeatureFlags
  ui?: UIOptions
  tracking?: TrackingConfig
  callbacks?: Callbacks
  monitoring?: MonitoringConfig
  cart?: CartConfig
}

callbacks​

interface Callbacks {
  onTokenExpiring?: () => Promise<string>
  onTokenRefreshed?: (newToken: string) => void
}

The only public callbacks are for Widget Token rotation. There are no public callbacks for search, result-click, filter-change, conversion or error. To react to widget activity, subscribe to the DOM CustomEvents — see Events.

cart​

When cart.enabled = true, the widget integrates with the host cart (WooCommerce, custom). The host implements all callbacks; the widget invokes them with the platform-agnostic signature:

interface CartConfig {
  enabled: boolean
  initialCount?: number
  onGetCart: () => Promise<CartState>
  onAddToCart: (productId: string, quantity: number, externalProductId?: string) => Promise<CartOperationResult>
  onRemoveFromCart: (itemKey: string) => Promise<CartOperationResult>
  onUpdateQuantity: (itemKey: string, quantity: number) => Promise<CartOperationResult>
  onCheckout: () => void
  canAddToCart?: (product: Product) => boolean
  externalUpdateEvent?: string  // default 'neuroon:cart-update'
  onSetDestinationCountry?: (countryCode: string) => Promise<CartOperationResult | void>
}

End-to-end pattern in Recipe · Custom cart bridge.

monitoring (optional)​

interface MonitoringConfig {
  applicationId: string
  clientToken: string
  // …SDK options
}

Only enabled for "managed" clients. If you configure it, the bundle initializes @datadog/browser-rum asynchronously.

styles​

Accepts a flat object (same values for both themes) or one per theme ({ light: {...}, dark: {...} }). See theming.md for the full list of --nrn-* variables and the RGB-triplet conversion.

Validation​

RuleMessage
token missing[NeuroonWidget] token is required
container missing[NeuroonWidget] container is required
apiUrl is not a valid URL[NeuroonWidget] Invalid apiUrl: …
theme not supportedwarning, fallback to auto
locale not supportedwarning, fallback to es
resultsPerPage <= 0[NeuroonWidget] resultsPerPage must be greater than 0

Further reading​

Last updated on