Callbacks are assigned as JS properties (they can't be HTML attributes). The rendering callbacks may return raw HTML — read Security.
Data extraction
Callback counterparts to the *-member attributes — use for computed values.
| Callback | Type | Description |
|---|---|---|
getValueCallback | (item) => string | number | Compute the value/id. |
getDisplayValueCallback | (item) => string | Compute the label. |
getSearchValueCallback | (item) => string | Compute the searchable text. |
getIconCallback | (item) => string | Compute the icon. |
getSubtitleCallback | (item) => string | Compute the subtitle. |
getGroupCallback | (item) => string | Compute the group name. |
getDisabledCallback | (item) => boolean | Compute disabled state. |
getFullTitleCallback | (item) => string | Compute the full/long title. |
getBadgeDisplayCallback | (item) => string | Compute badge text (separate from the label). |
getPathCallback v2.0.0 | (item) => string | Compute a node’s materialized tree path (counterpart to path-member; enables tree mode). |
getIsSelectableCallback v2.0.0 | (node) => boolean | Tree only. Whether a node is selectable — receives the built node, so it can read node.hasChildren (e.g. leaves-only). Counterpart to is-selectable-member. |
Tooltips & formatting
Property-only callbacks for tooltip content and value formatting.
| Callback | Type | Description |
|---|---|---|
getOptionTooltipCallback | (item) => string | HTMLElement | Tooltip content for an option row (default: label + subtitle). Requires enable-option-tooltips. |
getBadgeTooltipCallback | (item) => string | HTMLElement | Tooltip content for a badge. Requires enable-badge-tooltips. |
getRemoveButtonTooltipCallback | (item) => string | Tooltip text (title attribute) for a badge’s remove (×) button. |
getValueFormatCallback | (values) => string | Serialize the selected values for the hidden form input (overrides value-format). |
Rendering (may emit raw HTML)
These receive a presentation-aware context (isFullscreen, tree metadata) in v2.0.0.
| Callback | Type | Description |
|---|---|---|
renderOptionContentCallback | (item, ctx) => string | HTMLElement | Custom option-row content. |
renderBadgeContentCallback | (item, ctx) => string | HTMLElement | Custom content inside the built-in badge pill. |
renderBadgeCallback v2.0.0 | (item, ctx) => string | HTMLElement | null | Own the whole badge markup. Return null to fall back to the default pill; use data-action="remove" for the remove control. |
renderSelectedItemContentCallback | (item) => string | HTMLElement | Custom selected item in the popover. |
renderSelectedContentCallback | (item) => string | Custom single-select display. |
renderGroupLabelContentCallback | (groupName) => string | HTMLElement | Custom group header. |
getBadgeClassCallback | (item) => string | string[] | Extra CSS classes for badges. |
getSelectedItemClassCallback | (item) => string | string[] | Extra CSS classes for popover items. |
customStylesCallback | () => string | Inject a CSS string into the shadow root. |
Search & selection hooks
| Callback | Type | Description |
|---|---|---|
searchCallback | (term, signal?) => Promise<T[]> | Async search. Wire the AbortSignal into fetch to cancel. |
beforeSearchCallback | (term) => string | null | Pre-process the term; return null to veto. |
beforeSelectCallback | (option, selected) => boolean | string | void | Veto a selection (false), or veto + toast (string). |
beforeDeselectCallback | (option, selected) => boolean | string | void | Veto a deselection (false), or veto + toast (string). |
onSelect / onDeselect / onChange | (e: CustomEvent) => void | Fire-and-forget handlers. v2.0.0: now receive a CustomEvent, not a bare option. |
getCounterCallback | (count, moreCount?) => string | Format the selected-count label (i18n / pluralization). |
keydownCallback v2.0.0 | (ctx) => boolean | void | Intercept keydown before built-in handling; return true to suppress. ctx.controller exposes focus/select helpers. |
Add-new creation (v2.0.0)
| Callback | Type | Description |
|---|---|---|
addNewCallback v2.0.0 | (value) => T | null | Promise<T | null> | Create a new option from the typed text (async & cancelable; return null/undefined to abort). The returned option flows through the get*/render* callbacks. |
getAddNewTextCallback v2.0.0 | (value) => string | Compute the add-new prompt label (plain text). Takes precedence over add-new-text. |
onAddNew v2.0.0 | (detail) => void | Fires when the user commits creation. |
Example
Assigning callbacks