Notifications come two ways — bubbling DOM CustomEvents and the matching on* handler properties — plus interceptor callbacks that can veto an action before it happens.

EV01 Events

Select and deselect options to watch select and change fire.

Each CustomEvent carries detail.option, detail.selectedOptions and detail.selectedValues.

Event log

Pick an option to see events appear here…

Wiring the events 
 
 
Breaking change in v2.0.0: the onSelect / onDeselect / onChange handler properties now receive a CustomEvent (read e.detail.*), matching addEventListener — they used to receive the bare option. See the Migration guide.
 
 
EV02 beforeSelectCallback veto
 
Intercept a selection before it happens and cap the picks at three.
 
  
Select three items, then try a fourth — the pick is vetoed and a toast appears over the control.
 
 
Quick usage 
 
 
 
  • beforeSelectCallback runs before an option is added.
    •  
  • Return true to allow, false to veto silently.
    •  
  • Returning a string vetoes the selection and surfaces that string
						as a transient toast (via the built-in showMessage), visible even in the
						fullscreen overlay.
 
 
EV03 Add-new creation (v2.0.0)
 
Turn the picker into a creation tool — type something new and add it on the fly.
 
 
Add log 
Created items log here after the ~800ms delay…
 
Type a tag that is not listed (e.g. "Frontend"), then click the "Add …" prompt or press Enter.
 
 
Quick usage 
 
 
 
  • New in v2.0.0. With allow-add-new on, a search with no
						matches shows an “Add …” prompt (label templated by add-new-text, where {value} is the typed text).
    •  
  • addNewCallback is async and cancelable: return the created
						option to add + select it, or null/undefined to abort. While it
						runs, the prompt shows the pending text (add-new-pending-text).
    •  
  • The add event fires only when creation actually happens — e.detail carries the typed value, the created option, and the updated selection.