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.

CallbackTypeDescription
getValueCallback (item) => string | numberCompute the value/id.
getDisplayValueCallback (item) => stringCompute the label.
getSearchValueCallback (item) => stringCompute the searchable text.
getIconCallback (item) => stringCompute the icon.
getSubtitleCallback (item) => stringCompute the subtitle.
getGroupCallback (item) => stringCompute the group name.
getDisabledCallback (item) => booleanCompute disabled state.
getFullTitleCallback (item) => stringCompute the full/long title.
getBadgeDisplayCallback (item, ctx) => stringCompute badge text (separate from the label). v2.2.0: gets a BadgeContentRenderContext 2nd arg.
getPathCallback v2.0.0 (item) => stringCompute a node’s materialized tree path (counterpart to path-member; enables tree mode).
getIsSelectableCallback v2.0.0 (node) => booleanTree 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.

CallbackTypeDescription
getOptionTooltipCallback (item, ctx) => string | HTMLElementTooltip content for an option row (default: label + subtitle). Requires enable-option-tooltips. v2.2.0: gets an OptionContentRenderContext 2nd arg.
getBadgeTooltipCallback (item, ctx) => string | HTMLElementTooltip content for a badge. Requires enable-badge-tooltips. v2.2.0: gets a BadgeContentRenderContext 2nd arg.
getRemoveButtonTooltipCallback (item, ctx) => stringTooltip text (title attribute) for a badge’s remove (×) button. v2.2.0: gets a context 2nd arg.
getValueFormatCallback (values) => stringSerialize the selected values for the hidden form input (overrides value-format).

Rendering (may emit raw HTML)

Every render callback receives a presentation-aware context as its 2nd argument (presentation / isFullscreen / isModal, plus tree/group metadata) — v2.2.0 extended this to the selected-item and group callbacks too. All additive: one-argument callbacks keep working.

CallbackTypeDescription
renderOptionContentCallback (item, ctx) => string | HTMLElementCustom option-row content. ctx is an OptionContentRenderContext.
renderBadgeContentCallback (item, ctx) => string | HTMLElementCustom content inside the built-in badge pill. ctx is a BadgeContentRenderContext.
renderBadgeCallback v2.0.0 (item, ctx) => string | HTMLElement | nullOwn the whole badge markup. Return null to fall back to the default pill; use data-action="remove" for the remove control.
renderSelectedItemContentCallback v2.2.0 (item, ctx) => string | HTMLElementCustom selected item in the popover. v2.2.0: 2nd arg is a BadgeContentRenderContext (isInPopover=true).
renderSelectedContentCallback v2.2.0 (item, ctx) => stringCustom single-select display. v2.2.0: 2nd arg is a SelectedContentRenderContext.
renderGroupLabelContentCallback v2.2.0 (groupName, ctx) => string | HTMLElementCustom group header. v2.2.0: 2nd arg is a GroupLabelRenderContext — { groupName, members, selectedMembers, selectedCount, memberCount, selectableCount, checkState } plus the presentation fields — so a header can render its own per-group count/logic.
getBadgeClassCallback (item, ctx) => string | string[]Extra CSS classes for badges. v2.2.0: receives the same BadgeContentRenderContext as its render* twin.
getSelectedItemClassCallback (item, ctx) => string | string[]Extra CSS classes for popover items. v2.2.0: gets a context too (with isInPopover).
customStylesCallback () => stringInject a CSS string into the shadow root. Declarative twin: the custom-styles attribute (this callback wins when both are set).

Search & selection hooks

CallbackTypeDescription
searchCallback (term, signal?) => Promise<T[]>Async search. Wire the AbortSignal into fetch to cancel.
beforeSearchCallback (term) => string | nullPre-process the term; return null to veto.
beforeSelectCallback (option, selected) => boolean | string | voidVeto a selection (false), or veto + toast (string).
beforeDeselectCallback (option, selected) => boolean | string | voidVeto a deselection (false), or veto + toast (string).
onSelect / onDeselect / onChange (e: CustomEvent) => voidFire-and-forget handlers. v2.0.0: now receive a CustomEvent, not a bare option.
getCounterCallback (count, moreCount?) => stringFormat the count-mode / “+N more” label (e.g. 3 selected) — i18n / pluralization. Distinct from getCountLabelCallback, which formats the small chip.
getCountLabelCallback v2.2.0 (selected, total) => stringOne formatter for the small count chip shown in both the in-input counter and each group header — so they always read the same. Default [selected] (e.g. [3]); return `${s}/${t}` for an x-of-total style (total is the whole list for the in-input counter, the group’s member count for a header).
getSelectedOrderCallback v2.2.0 (item) => string | numberSort key for the selected-items display when selected-order="member" (overrides selected-order-member).
selectedOrderCompareCallback v2.2.0 (a, b) => numberComparator for the selected-items display when selected-order="custom" — standard (a,b)=>number contract.
keydownCallback v2.0.0 (ctx) => boolean | voidIntercept keydown before built-in handling; return true to suppress. ctx.controller exposes focus/select helpers (a MultiSelectKeyboardController).

Add-new creation (v2.0.0)

CallbackTypeDescription
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) => stringCompute the add-new prompt label (plain text). Takes precedence over add-new-text.
onAddNew v2.0.0 (detail) => voidFires when the user commits creation.

Example

Assigning callbacks