JavaScript SDK Reference

All calls go through window.LumioWidget(action, ...args). The global is available after the loader script runs. Calls made before the loader is ready are queued and replayed automatically.

init

Initialise the widget and render the launcher.

LumioWidget('init', { widgetId: 'YOUR_WIDGET_ID' })

Call init once, before any other SDK method.

display — placement & launcher

Every field is optional and overrides the dashboard default for that field. Omit display entirely to let the dashboard own placement (recommended — see Installing the Widget).

LumioWidget('init', {
  widgetId: 'YOUR_WIDGET_ID',
  display: { position: 'left', style: 'iconAndText', text: 'Help', iconImage: 'question' },
})

Precedence: dashboard default → snippet display override → manual.

config

Update placement & launcher at runtime. Accepts the same display object as init (merged into the current config) and re-renders the launcher in place.

LumioWidget('config', { display: { position: 'left', style: 'manual' } })

identify

Associate the current browser session with a logged-in user.

LumioWidget('identify', {
  userId: 'user_123',
  signature: '<server-computed hmac>',
  name: 'Alice',
  email: 'alice@example.com',
  properties: { plan: 'pro' },
})

See Identifying Users for the server-side signing example.

open / close / toggle

Programmatically control the widget panel.

LumioWidget('open')    // open the panel
LumioWidget('close')   // close the panel
LumioWidget('toggle')  // toggle open/closed

navigate

Navigate to a top-level surface inside the panel.

LumioWidget('navigate', '/updates')  // open Product Updates
LumioWidget('navigate', '/docs')     // open Docs

Accepted routes: '/updates' | '/docs'.

article

Open a specific doc by its slug or page id (copy a ready value from the dashboard under Widget → Install → Contextual links).

LumioWidget('article', 'settlement-tats')                       // focused sheet (default)
LumioWidget('article', 'settlement-tats', { type: 'sidebar' })  // full panel
LumioWidget('article', 'settlement-tats', { type: 'modal' })    // centered modal
LumioWidget('article', 'settlement-tats', { type: 'popover' })  // corner card

Use this for contextual deep-links from your UI. For plain links you can also use the zero-JS data-lumio-article attribute.

search

Open Docs with a pre-filled search query.

LumioWidget('search', 'billing')

suggest

Show contextual doc suggestions — up to 10 articles surfaced near the launcher.

LumioWidget('suggest', ['PAGE_ID_1', 'PAGE_ID_2', 'PAGE_ID_3'])

Pass an array of Notion page ids (max 10). Useful for surfacing relevant help based on what the user is currently doing.

event

Report a SPA route change so Lumio can evaluate URL-based announcement targeting.

LumioWidget('event', {
  type: 'page-viewed',
  url: window.location.href,
  title: document.title,
})

Call this after every client-side navigation.

announce

Manually trigger an announcement by id.

LumioWidget('announce', 'ANNOUNCEMENT_ID')

// With options
LumioWidget('announce', 'ANNOUNCEMENT_ID', { delay: 2000, force: true })

on / off

Subscribe to or unsubscribe from widget events.

LumioWidget('on', 'open', () => console.log('widget opened'))
LumioWidget('off', 'open', handler)

Available events