@llselect/core

Select classes

abstract LLSelectBase

Defined in: base.ts:868

Abstract base for all select variants. Owns DOM scaffolding, ARIA wiring, positioning, keyboard navigation, lazy popup-list rendering, and outside-click handling. Subclasses (LLSelectSingle, LLSelectMultiple) own chosen-state, decide what happens on item click, and customise the trigger text via renderTriggerContent.

Extended by

• LLSelectSingle
• LLSelectMultiple

Type Parameters

Items

getItems()

getItems(): readonly T[]

Defined in: base.ts:1582

Return the current item list, in data order (as passed to setItems).

• The rendered list may differ in order and content: see getVisibleItems.
• Returns the LIVE internal array, typed read-only. Do not mutate it (TS blocks it; plain-JS callers must treat it as frozen).
• Structural mutation would silently bypass chosen-state reconciliation, re-filtering, and re-render. Replace the list via setItems instead.
• Mutating item OBJECTS + rerender() is the supported in-place path.

Returns

readonly T[]

setItems()

setItems(items): void

Defined in: base.ts:1670

Replace the item list.

• The input is shallow-copied; later external mutation does not affect the select.
• Items MUST be unique under compareFn (it defines item identity, and the selection is a set). Duplicates render stale selection DOM; the default compareFn warns once per page, a custom compareFn is the caller's responsibility (not scanned, to keep large lists cheap).
• If the popup is open, it re-renders now. While closed, the DOM is built lazily on the next open().
• Both shipped variants re-render the trigger content from onItemsChanged (the multiple count total, custom content that reads items).
• LLSelectMultiple's triggerDisplay: 'tags' mode is opt-in; 'count' is the default.
• When triggerDisplay is 'tags', that content render is one chip per chosen item, unless createTriggerContentElFn replaces the content.
• Subclasses may reconcile chosen-state via onItemsChanged (e.g. single mode drops a chosen value that is no longer in the list).

Parameters

Returns

void

getVisibleItems()

getVisibleItems(): readonly T[]

Defined in: base.ts:3241

Return the items the popup list renders, in display order.

items                (setItems)
  |  gather          (only with grouping on; result cached until setItems)
  v
display base list
  |  filter query    (only while a query is active)
  v
visible items        (this method's return value)
  |  render
  v
DOM rows

• If no filter query is active (including while closed), it returns the full list, gathered per gatherGroups when grouping is on.
• If a filter query is active, it returns the matching subset.
• Disabled items are included. They render (grayed); only actions skip them (keyboard focus, the choose-all row's subset).
• Returns the LIVE internal array, typed read-only. Never mutate it (see getItems).
• Subclasses use it too (e.g. for selection-by-index), and may override it to add a step: LLSelectMultiple does for hideChosenRows.

Returns

readonly T[]

Open & close

open()

open(): void

Defined in: base.ts:1363

Open the popup. Builds item elements lazily, attaches the positioner (which auto-closes if the trigger is scrolled out of view), wires the outside-click handler, and moves keyboard focus into the item list. No-op if already open.

Returns

void

close()

close(): void

Defined in: base.ts:1447

Close the popup. Detaches positioner and outside-click listener, clears the item DOM, and resets focused-item state. No-op if already closed.

Focus return is decided automatically: when DOM focus is still inside the popup at the moment of close - the filter input (Esc on an empty filter, a single-select pick, an outside press on a non-focusable area) or a focusable control the app placed in a header / footer slot (Esc there, or close() called from its own click) - focus is returned to the trigger. Tab-away and outside clicks on focusable elements have already moved focus elsewhere, so we leave it alone.

Returns

void

toggle()

toggle(): void

Defined in: base.ts:1552

Open if closed, close if open.

Returns

void

isOpened()

isOpened(): boolean

Defined in: base.ts:1568

Whether the popup is currently open.

• Pairs with isDisabled() (state read via method).
• The same state is mirrored on the DOM as CSS hooks: data-state="open|closed" on the trigger, classIdMap.openClass on the root.

Returns

boolean

Trigger

setPlaceholder()

setPlaceholder(placeholder): void

Defined in: base.ts:1643

Replace the trigger placeholder text at runtime. It is one of the two settings with a runtime setter (the other is setUiTranslationPack); both are copy. The rule: LLSelectBaseSettings.

• null = fall back to the pack default (uiTranslationPack.triggerPlaceholder), mirroring an unset constructor placeholder. An explicit value keeps winning over later setUiTranslationPack calls, exactly like the constructor input.
• Takes effect immediately. Visible only while nothing is chosen - the placeholder never renders otherwise (the trigger is still re-rendered, which also refreshes the hidden accessible-value mirror).

Parameters

Returns

void

Filtering

getFilterQuery()

getFilterQuery(): string

Defined in: base.ts:3271

Return the filter input's current query, exactly the string passed to filterFn.

• It is '' while the popup is closed, the filter is inactive, or the input is empty.
• It resets on close: each open cycle starts empty.

Returns

string

Disabling

setDisabled()

setDisabled(value): void

Defined in: base.ts:1706

Enable or disable the whole control. Disabled: the trigger gets aria-disabled + data-disabled (never the native disabled attribute, which would suppress the hover / focus events a tooltip needs), opening is blocked, an open popup closes, and the trigger leaves the tab order unless focusableWhenDisabled is set. Stored as state, mirroring setItems / setChosenItems (this design keeps mutable state out of settings).

Parameters

Returns

void

isDisabled()

isDisabled(): boolean

Defined in: base.ts:1717

Whether the whole control is disabled.

Returns

boolean

i18n

getUiTranslationPack()

getUiTranslationPack(): Readonly<LLSelectUiTranslationPack>

Defined in: base.ts:1595

Return the resolved UI strings: the built-in English defaults merged with the uiTranslationPack setting.

• Reuse these in your own UI instead of keeping a second translation source. For example, a tag remove button tooltip: sel.getUiTranslationPack().tagRemoveButtonAriaLabel(label).
• Returns the LIVE object. Treat it as immutable, like getItems.

Returns

Readonly<LLSelectUiTranslationPack>

setUiTranslationPack()

setUiTranslationPack(uiTranslationPack): void

Defined in: base.ts:1616

Replace the UI-translation pack at runtime, so switching language needs no re-new.

• One of the two settings with a runtime setter (the other is setPlaceholder); both are copy. The rule: LLSelectBaseSettings.
• The pack is resolved exactly like the constructor's: merged over the built-in English pack, NOT over the previously set pack.
• An explicit constructor placeholder keeps winning over the new pack's triggerPlaceholder.
• Re-renders the trigger and the open popup.
• Also re-applies the pack-owned attributes rerender() cannot reach: the filter input placeholder and its fallback aria-label.
• The clear button needs no such step: rerender() rebuilds it, and the rebuild reads the new pack - unless a createTriggerClearButtonEl override returns the previous element, which then owns the label.

Parameters

Returns

void

Lifecycle

Constructor

new LLSelectBase<T, GroupKey, S>(targetEl, settings?, subclassSettings?): LLSelectBase<T, GroupKey, S>

Defined in: base.ts:1098

Parameters

Returns

LLSelectBase<T, GroupKey, S>

rerender()

rerender(): void

Defined in: base.ts:1517

Rebuild the trigger and (while open) the popup list from current state.

• Use it after mutating item OBJECTS in place (e.g. users[0].name = 'X'). The library cannot detect that on its own.
• It re-derives the display order (the gatherGroups gather).
• While the filter is active, it re-runs the filter against the current item text.
• The refresh is purely visual: it does NOT fire onChange and does NOT run onItemsChanged.
• Orchestrator: composes renderTrigger + renderPopupList; touches no DOM directly.

Returns

void

destroy()

destroy(): void

Defined in: base.ts:1537

Tear down the instance: close the popup (which detaches every document / window listener and the positioner), unwire labelEl (click listener removed, a minted id removed), remove the library's class and inline styles from the caller's mount element, and empty it. Idempotent. The instance must not be used afterwards.

• REQUIRED before discarding an instance that might be OPEN (framework wrappers: call this on unmount) - skipping it there leaks the outside-click / focusout / scroll / resize listeners.
• Discarding a CLOSED instance without destroy() leaks nothing; it only leaves the root class and overflow-anchor style on the mount.

Returns

void

DOM elements

rootEl

readonly rootEl: HTMLElement

Defined in: base.ts:875

The caller-passed mount element, now decorated as the select's root. Library does not replace this node, so the caller's original reference, id, and data-* attributes stay valid.

triggerEl

readonly triggerEl: HTMLElement

Defined in: base.ts:885

The interactive trigger element. Receives focus, click, and keydown events; carries aria-expanded, aria-controls, and data-state="open|closed". Its role depends on the filter mode: combobox while the filter is inactive (it then also hosts aria-activedescendant) and button while a filterable popup is open (the filter input hosts aria-activedescendant). See docs/llm/A11Y.md.

triggerContentEl

readonly triggerContentEl: HTMLElement

Defined in: base.ts:892

Inner span inside the trigger where text/tags are written. Subclasses' renderTriggerContent writes here so the sibling arrow slot is preserved across re-renders.

popupEl

readonly popupEl: HTMLElement

Defined in: base.ts:909

The outer popup wrapper. Has no ARIA role itself - it just hosts the popup chrome (future: filter input, toggle-all control) and the inner popupListEl. Hidden via the hidden attribute when closed; positioned via inline styles by the positioner when open.

popupListEl

readonly popupListEl: HTMLElement

Defined in: base.ts:917

The inner element with role="listbox", holding the item children. Sits inside popupEl so siblings (filter input, toggle-all) can live above it without violating ARIA's "listbox children must be options" rule. The trigger's aria-controls points to this element.

popupHeaderEl

readonly popupHeaderEl: HTMLElement | null

Defined in: base.ts:925

The pinned header container between the filter input and the listbox, or null when no header content was built. No ARIA role; outside the scroll area. Built once in the constructor (createPopupHeaderEl) and kept until destroy(); the library never rebuilds or moves it.

popupFooterEl

readonly popupFooterEl: HTMLElement | null

Defined in: base.ts:932

The pinned footer container at the bottom of the popup, after the no-results message, or null when no footer content was built. Same lifecycle as popupHeaderEl.

popupListPinnedLeadingRowsEl

readonly popupListPinnedLeadingRowsEl: HTMLElement | null

Defined in: base.ts:950

The wrapper around the pinned leading rows, or null.

• Built once in the constructor when popupListLeadingRowsPinned is true; null otherwise.
• A div with role="presentation" and class popupListPinnedLeadingRowsClass; the library sets position: sticky and top: 0 on it inline.
• In the listbox only while the leading rows exist. The library moves it in and out on every list render. Its classes are yours to change after new.
• data-edge-to-items is set on every list render: "true" when that render lists items, "false" when it lists none; absent before the first render.
• It is a CSS hook for the themes: they draw the block's edge line only when it is true, so two blocks that touch draw no line between them.

popupListPinnedTrailingRowsEl

readonly popupListPinnedTrailingRowsEl: HTMLElement | null

Defined in: base.ts:957

The wrapper around the pinned trailing rows, or null.

• Same contract as popupListPinnedLeadingRowsEl, for popupListTrailingRowsPinned, with bottom: 0.

classIdMap

readonly classIdMap: LLSelectClassIdMap

Defined in: base.ts:962

Resolved class names and ids for this instance.

triggerValueEl

protected readonly triggerValueEl: HTMLElement

Defined in: base.ts:901

Hidden root-level span (sibling of the trigger) mirroring the current value as plain text. Kept in sync by commitTriggerContentToDom; referenced by the filterable-mode aria-labelledby chain (see classIdMap.triggerValueId). Outside the trigger so triggerEl.textContent stays exactly the visible content.

Subclassing: reactions

onOpened()

protected onOpened(): void

Defined in: base.ts:1753

Subclass hook: called once after the popup finishes opening. Default no-op. The onOpen setting fires alongside this (both run) - hook for subclass logic, setting for consumer notification.

Returns

void

onClosed()

protected onClosed(): void

Defined in: base.ts:1758

Subclass hook: called once after the popup finishes closing. Pairs with the onClose setting (both run).

Returns

void

onChosenChanged()

protected onChosenChanged(): void

Defined in: base.ts:1765

Subclass hook: called after the chosen state actually changed, right before the variant's onChange setting fires (hook first, both run - same pairing as onOpened / onClosed). Default no-op.

Returns

void

onItemsChanged()

protected onItemsChanged(): void

Defined in: base.ts:1772

Called after setItems finishes. Override to reconcile state that depends on the item list (e.g. clear a chosen value that disappeared). Default no-op.

Returns

void

onItemActivated()

protected onItemActivated(_item): void

Defined in: base.ts:2399

Called when an item is activated (click or keyboard select). Default no-op; subclasses implement their selection behaviour (single mode picks and closes, multiple mode toggles and keeps the popup open).

Parameters

Returns

void

onPopupListActionRowActivated()

protected onPopupListActionRowActivated(row): void

Defined in: base.ts:2522

Subclass hook: an action row was activated.

• The library calls it on Enter, on Space while the filter is inactive, and on click, after the disabled re-check, as a user change. You never call it. row comes from the library: the activated entry.
• Default calls the entry's onActivate. The library changes nothing else: choosing and closing are the entry's job.
• Override to react before or after: do your work, then call super.onPopupListActionRowActivated(row). Without that call the entry's onActivate never runs.

Parameters

Returns

void

withUserChangeSource()

protected withUserChangeSource<R>(fn): R

Defined in: base.ts:2582

Run fn with chosen-state changes attributed to the user. The library wraps exactly its pointer / keyboard entry points with it - option activation, the tag remove button, the clear button, the choose-all row; everything else reports 'api'.

Type Parameters

Parameters

Returns

R

onChooseAllRowActivated()

protected onChooseAllRowActivated(): void

Defined in: base.ts:2597

Subclass hook: the choose-all row was activated - Enter while it is focused (subclasses also wire their row's click handler to this). Default no-op.

Returns

void

Subclassing: rendering

renderTrigger()

protected renderTrigger(): void

Defined in: base.ts:1810

Orchestrator: composes the clear-button rebuild + renderTriggerContent + renderTriggerArrow to (re)build the whole trigger from state; touches no DOM directly. Subclasses normally override renderTriggerContent, not this.

• Runs on every change of the chosen value, the placeholder or the pack.
• rerender() runs it too.
• While clearable is on, the first run builds the clear button and every later run swaps it for whatever createTriggerClearButtonEl returns: a fresh button from the base implementation, like the arrow. An override may return the previous element; it is then kept in place.
• If the button is rebuilt and the old one held focus - on it or inside its icon - the rebuilt BUTTON gets it.
• If the builder returned the same element, nothing was rebuilt, and focus goes back to the node that held it, if that node is still inside the button and can take focus; otherwise focus stays on the button.
• setItems runs renderTriggerContent alone, because only the content reads the list (the multiple count total, a custom createTriggerContentElFn's items).
• A setItems that drops the chosen entry runs the whole trigger.
• Runs once from the LLSelectSingle / LLSelectMultiple constructor, right after super().
• On that first run a FURTHER subclass's own fields are still undefined: JS runs a subclass's field initializers only after its super constructor returns (virtual-call-in-constructor). An override of a trigger method (renderTriggerContent, or a create*El it calls) that reads such a field sees undefined there.
• The recipe: put construction-time configuration in the typed subclassSettings constructor param. this.settings is complete before any construction code runs.
• For genuine instance state, tolerate defaults during construction, or call rerender() at the end of your own constructor.
• The popup-list methods do NOT run here; they wait for open(). See DESIGN.md "Customization model".

Returns

void

commitTriggerContentToDom()

protected commitTriggerContentToDom(content, plainTextValue?): void

Defined in: base.ts:1833

Write the trigger's content slot (triggerContentEl), replacing whatever was there; the sibling arrow slot is untouched. The single DOM-writing primitive behind every renderTriggerContent path.

• string -> set as textContent (plain text, NOT parsed as HTML). Used for the default placeholder / itemToString text / count summary.
• HTMLElement -> inserted as-is via replaceChildren; caller owns the node. Used for whatever the createTriggerContentElFn setting returned.
• Also mirrors the value into the hidden triggerValueEl (the accessible name source): the string itself, else plainTextValue, else the element's textContent. Pass plainTextValue whenever the element contains labelled controls (tag remove buttons) or icon-only content - the mirror is what AT announces as the field's value. Called by renderTriggerContent - the base default and the LLSelectSingle / LLSelectMultiple overrides.

Parameters

Returns

void

syncEmptyStateToDom()

protected syncEmptyStateToDom(): void

Defined in: base.ts:1850

Mirror the empty/filled state onto the trigger's data-empty attribute ("true" when isEmpty(), else "false"). A CSS / AT styling hook, independent of the rendered content. Called by the subclass renderTriggerContent overrides.

Returns

void

renderTriggerContent()

protected renderTriggerContent(): void

Defined in: base.ts:1873

Orchestrator: composes the *ToDom primitives to (re)build the trigger's content slot from state; touches no DOM directly. Override in subclasses to display the chosen value(s); this base default commits the placeholder and the empty flag. Always write via commitTriggerContentToDom (content) and syncEmptyStateToDom (the data-empty flag), never triggerContentEl directly, so the sibling arrow slot is always preserved.

Returns

void

createTriggerArrowContentEl()

protected createTriggerArrowContentEl(state): HTMLElement | SVGElement | null

Defined in: base.ts:1896

Trigger arrow element for the given open state.

• Default reads createTriggerArrowContentElFn; null (setting unset, or returned for a state) = no arrow for that state.
• Override only when extending; for one-off arrows pass the setting. Mirrors createTriggerClearButtonEl / createItemContentEl.

Parameters

Returns

HTMLElement | SVGElement | null

renderPopupList()

protected renderPopupList(): void

Defined in: base.ts:1929

Orchestrator: composes createItemEl (build) + computePopupSegments + commitPopupSegmentsToDom (write) to rebuild the popup list from getVisibleItems(); touches no DOM directly. Called by open() and by setItems() while open. Also clamps focusedIndex if the list shrank and re-applies focus visuals.

• Extend it by wrapping: override, do your work before or after, then call super.renderPopupList(). The ui-select bridge frees its row scopes this way. Or override one of the methods it calls through this: createItemEl, createPopupListChooseAllRowEl, createPopupListLeadingActionRowEl / createPopupListTrailingActionRowEl, itemToGroupKey, getVisibleItems.
• Its other internals stay private on purpose. They re-establish the itemEls[i] <-> getVisibleItems()[i] alignment as one unit, so no subclass can leave keyboard nav or aria-activedescendant half-synced.

Returns

void

createGroupEl()

protected createGroupEl(key, index, items, itemEls): HTMLElement

Defined in: base.ts:2064

Build the whole DOM element for one group container.

• The library calls it, once per group of the current render, on every list render. You never call it yourself.
• All four params come from the library. Forward them to super unchanged.
• index is the group's position among this render's groups, counted from 0. It only mints the group id. It is not an identity: it changes whenever the visible list changes.
• To change only the label's content, do not override this. Pass the createGroupLabelContentElFn setting instead.
• To change the element itself, override it, call super.createGroupEl(...), and edit the returned element. Keep the role and aria-label the base set.
• Internals: the base sets the id, role="group" named by groupKeyToString (aria-label), an aria-hidden visible label element filled from createGroupLabelContentEl (else the plain label text), then the group's item elements; aria-disabled + data-disabled when the group is disabled.

Parameters

Returns

HTMLElement

createGroupLabelContentEl()

protected createGroupLabelContentEl(key, itemsInGroup): HTMLElement | null

Defined in: base.ts:2098

Group label -> its visible content element (icon / count badge / rich markup). Mirrors createItemContentEl.

• Default reads createGroupLabelContentElFn, else null so createGroupEl uses plain text from groupKeyToString.
• The group's accessible name stays groupKeyToString (container aria-label); this fills only the visible, aria-hidden label content.
• Override only when extending; for one-off rich labels pass the setting.

Parameters

Returns

HTMLElement | null

replacePopupListItemElInDom()

protected replacePopupListItemElInDom(item): void

Defined in: base.ts:2112

Re-render a single item's element in place instead of rebuilding the whole popup list. The DOM work is O(1) regardless of list size, so flipping one selection in a 10k-item list does not recreate 10k nodes (the lookup to find the item is O(n), but that is a cheap comparison loop next to DOM mutation). No-op if the popup is closed or the item is not in the current list. Used by multi-select toggle.

Parameters

Returns

void

createItemEl()

protected createItemEl(item, index): HTMLElement

Defined in: base.ts:2161

Build the whole DOM element for one option row.

• The library calls it, once per row of getVisibleItems(), on every list render. You never call it yourself.
• Both params come from the library. Forward them to super unchanged.
• item is the row's item.
• index is the row's position in getVisibleItems(), counted from 0. That is the list as rendered: grouped, filtered, minus hidden chosen rows. It is NOT the position in items.
• index is not an identity. It changes whenever the visible list changes. Item identity is compareFn. Never store it.
• To change only what a row shows, do not override this. Pass the createItemContentElFn setting instead.
• To change the element itself, override it, call super.createItemEl(item, index), and edit the returned element: add a class, a title, a wrapper. Demo sections 9.1, 13.1 and 13.2 do this.
• Keep the id and role the base set. Do not put focusable controls inside the row. The row itself is the control.
• The element is rebuilt on every render. Do not keep a reference to it.
• Internals: the base sets id (<listbox id>-item<index>, the target of aria-activedescendant), role="option", the visible content from createItemContentEl (else textContent from itemToString), aria-label = itemToString when the content is custom, aria-disabled plus the disabled class when isItemEffectivelyDisabled, and a click handler that focuses the row by index, then runs onItemActivated.

Parameters

Returns

HTMLElement

createItemContentEl()

protected createItemContentEl(item): HTMLElement | null

Defined in: base.ts:2222

Item -> the visible content of its list row (icon + text etc.).

• Default reads createItemContentElFn, else null so createItemEl uses the plain-text default from itemToString.
• Override only when extending; for one-off rich content pass the setting.

Parameters

Returns

HTMLElement | null

createPopupListLeadingActionRowEl()

protected createPopupListLeadingActionRowEl(row, index): HTMLElement

Defined in: base.ts:2427

Build the whole DOM element for one leading action row (above the items).

• The library calls it, once per entry of popupListLeadingActionRows, on every list render and after every chosen change. You never call it.
• Both params come from the library. Forward them to super unchanged. row is the entry; index is its position in that array, counted from 0, used to mint the id. It is not an identity.
• To change only what the row shows, do not override this: give the entry a createContentElFn.
• To change the element itself, override it, call super.createPopupListLeadingActionRowEl(row, index), and edit the returned element. Keep the id and role; put no focusable control inside.
• Internals: a div with role="option", the id <listbox id>-action-row-leading<index>, itemClass plus popupListActionRowClass, the visible content from createPopupListActionRowContentEl (else textContent from textFn), aria-label = textFn() when the content is custom, and either aria-disabled plus the disabled class (isPopupListActionRowDisabled) or a click handler that focuses the row, then runs onPopupListActionRowActivated. No aria-selected: a command has no selected state.

Parameters

Returns

HTMLElement

createPopupListTrailingActionRowEl()

protected createPopupListTrailingActionRowEl(row, index): HTMLElement

Defined in: base.ts:2450

Build the whole DOM element for one trailing action row (below the items).

• The library calls it, once per entry of popupListTrailingActionRows, on every list render and after every chosen change. You never call it.
• Both params come from the library. Forward them to super unchanged. row is the entry; index is its position in that array, counted from 0, used to mint the id. It is not an identity.
• To change only what the row shows, do not override this: give the entry a createContentElFn.
• To change the element itself, override it, call super.createPopupListTrailingActionRowEl(row, index), and edit the returned element. Keep the id and role; put no focusable control inside.
• Internals: identical to createPopupListLeadingActionRowEl except the id, <listbox id>-action-row-trailing<index>.

Parameters

Returns

HTMLElement

createPopupListActionRowContentEl()

protected createPopupListActionRowContentEl(row): HTMLElement | null

Defined in: base.ts:2493

An action row's visible content element.

• The library calls it from the row builders, once per row render. You never call it. row comes from the library.
• Default reads the entry's createContentElFn; null (unset, or returned) = plain text from textFn.
• Override only when extending; for one-off content give the entry a createContentElFn.

Parameters

Returns

HTMLElement | null

replacePopupListActionRowElsInDom()

protected replacePopupListActionRowElsInDom(): void

Defined in: base.ts:2538

Rebuild every rendered action row in place, so textFn / disabledFn reflect the current state; the row holding the active option keeps it.

• The library calls it after every chosen change, right after onChange fired (a row's text may read what the handler wrote). Subclasses may call it after a state change of their own.
• No-op while closed, or when both row arrays are empty - instances without rows pay nothing.
• O(rows) DOM work; the item rows are untouched.

Returns

void

createPopupListChooseAllRowEl()

protected createPopupListChooseAllRowEl(): HTMLElement | null

Defined in: base.ts:2573

Optional non-item role="option" row placed first, at the TOP of the listbox: inside the arrow-key ring (ArrowUp from the first item reaches it, Home lands on it, up-actions clamp there) but never inside itemEls, so the itemEls[i] <-> getVisibleItems()[i] alignment is untouched. Rebuilt on every renderPopupList. Base default: null = no choose-all row. LLSelectMultiple builds its choose-all row here (chooseAllRow setting).

Returns

HTMLElement | null

replaceChooseAllRowElInDom()

protected replaceChooseAllRowElInDom(): void

Defined in: base.ts:2652

Rebuild the choose-all row in place (tri-state / text refresh) without touching the item elements - O(1) DOM work, mirroring replacePopupListItemElInDom. Falls back to a full renderPopupList when the row becomes inapplicable (builder returns null). No-op while closed or when no choose-all row is rendered.

Returns

void

createTriggerClearButtonEl()

protected createTriggerClearButtonEl(): HTMLElement

Defined in: base.ts:3047

Build the clear (x) button for the clearable trigger slot.

• The library owns the button, its click (stops propagation so it never toggles the popup, then clearSelection; a no-op while the control is disabled) and its aria-label (text from uiTranslationPack.triggerClearButtonAriaLabel).
• createTriggerClearButtonContentElFn optionally fills the icon; else the theme's CSS glyph draws it.
• The theme hides the button via data-empty while nothing is chosen.
• It runs on every trigger render (renderTrigger).
• The first run builds the button.
• For LLSelectSingle / LLSelectMultiple and their subclasses, that first run is the variant constructor's render, right after super(), so it happens before a FURTHER subclass's field initializers.
• A direct LLSelectBase subclass gets the button on its first trigger render (its own renderTrigger() call, or rerender() / setPlaceholder); until then the trigger is unrendered and there is no button.
• Every later run (a value change, setPlaceholder, setUiTranslationPack, rerender()) swaps the button in place, unless this method returns the previous element - then it stays in place.
• The base implementation returns a fresh element each run, so, like the arrow, nothing put on it from outside survives a render; customize it here.
• An override that returns the same element every time owns everything the rebuild would otherwise refresh on it, including its aria-label after setUiTranslationPack.
• An override that reads subclass fields calls rerender() at the end of its constructor, like every other trigger method.

Returns

HTMLElement

createTriggerClearButtonContentEl()

protected createTriggerClearButtonContentEl(): HTMLElement | SVGElement | null

Defined in: base.ts:3174

Clear button's visible content (its x icon).

• Default reads createTriggerClearButtonContentElFn; null (setting unset, or returned) = no icon - the theme's CSS glyph draws the x.
• Override only when extending; for one-off icons pass the setting.

Returns

HTMLElement | SVGElement | null

createPopupListNoResultsContentEl()

protected createPopupListNoResultsContentEl(query): HTMLElement | null

Defined in: base.ts:3356

The no-results message's visible content (rich empty-state).

• Default reads createPopupListNoResultsContentElFn; null (setting unset, or returned) = plain text from uiTranslationPack.popupListNoResults.
• Override only when extending; for one-off content pass the setting.

Parameters

Returns

HTMLElement | null

createPopupHeaderEl()

protected createPopupHeaderEl(): HTMLElement | null

Defined in: base.ts:3376

Build the pinned header container between the filter input and the listbox.

• The library calls it once, inside the constructor. You never call it.
• It takes no params. The default asks createPopupHeaderContentEl for content; null content = no container, and popupHeaderEl stays null.
• To supply content without subclassing, pass createPopupHeaderContentElFn.
• To change the container itself, override it: call super.createPopupHeaderEl() and edit the returned element, or return your own div. Returning non-null builds the slot even without the setting. Keep it role-free: it is not part of the listbox.
• Internals: the base builds a div with classIdMap.popupHeaderClass and inline flex: none (the popup is a flex column and only the listbox may flex), then appends the content.

Returns

HTMLElement | null

createPopupHeaderContentEl()

protected createPopupHeaderContentEl(): HTMLElement | null

Defined in: base.ts:3390

The pinned header's content element.

• The library calls it once, from createPopupHeaderEl, inside the constructor. You never call it.
• Default calls createPopupHeaderContentElFn with a LLSelectConstructionContext; null (setting unset, or returned) = no header at all.
• Override only when extending; for one-off content pass the setting.

Returns

HTMLElement | null

createPopupFooterEl()

protected createPopupFooterEl(): HTMLElement | null

Defined in: base.ts:3410

Build the pinned footer container at the bottom of the popup.

• The library calls it once, inside the constructor. You never call it.
• It takes no params. The default asks createPopupFooterContentEl for content; null content = no container, and popupFooterEl stays null.
• To supply content without subclassing, pass createPopupFooterContentElFn.
• To change the container itself, override it: call super.createPopupFooterEl() and edit the returned element, or return your own div. Returning non-null builds the slot even without the setting. Keep it role-free: it is not part of the listbox.
• Internals: the base builds a div with classIdMap.popupFooterClass and inline flex: none (only the listbox may flex), then appends the content.

Returns

HTMLElement | null

createPopupFooterContentEl()

protected createPopupFooterContentEl(): HTMLElement | null

Defined in: base.ts:3424

The pinned footer's content element.

• The library calls it once, from createPopupFooterEl, inside the constructor. You never call it.
• Default calls createPopupFooterContentElFn with a LLSelectConstructionContext; null (setting unset, or returned) = no footer at all.
• Override only when extending; for one-off content pass the setting.

Returns

HTMLElement | null

Subclassing: semantics

isEmpty()

protected isEmpty(): boolean

Defined in: base.ts:1860

Whether the control currently has no selection (drives data-empty). Base default is always true (the base trigger only shows the placeholder); LLSelectSingle / LLSelectMultiple override it.

Returns

boolean

itemToString()

protected itemToString(item): string

Defined in: base.ts:2210

Map an item to its display string. The library calls this everywhere it needs an item's text: list rows, the single trigger text, default filter.

• Default reads the itemToStringFn setting, else String(item).
• Configure via itemToStringFn (no subclass needed).
• Override only when extending (a new select type); your override replaces the default. For HTML content, subclass createItemEl.

Parameters

Returns

string

isItemEffectivelyDisabled()

protected isItemEffectivelyDisabled(item): boolean

Defined in: base.ts:2236

Whether item is effectively disabled - by itemDisabledFn, or because its group is disabled (groupDisabledFn). Group-disabled layers on top, so every item-disabled behavior (no selection, keyboard skip, aria) covers grouped items with no extra code. False when neither applies. The whole-control disabled state (isDisabled()) is a separate layer, not part of this answer.

Parameters

Returns

boolean

itemToGroupKey()

protected itemToGroupKey(item): GroupKey | null

Defined in: base.ts:2255

Map an item to its group key, or null when it belongs to no group. The authoritative method: rendering, the gatherGroups gather, and the disabled layer all resolve keys through this method, so an override drives them all - returning keys turns grouping on even with the setting unset (all-null keys = flat list). An override reading external state must call rerender() after that state changes (same contract as mutating item objects).

• Default reads itemToGroupKeyFn, else null (grouping off).
• Override only when extending; configure via the setting.

Parameters

Returns

GroupKey | null

groupKeyToString()

protected groupKeyToString(key): string

Defined in: base.ts:2265

Map a group key to its label display text.

• Default reads groupKeyToStringFn, else String(key).

Parameters

Returns

string

isGroupDisabled()

protected isGroupDisabled(key): boolean

Defined in: base.ts:2274

Whether the whole group key is disabled per groupDisabledFn (false when unset).

Parameters

Returns

boolean

isPopupListActionRowDisabled()

protected isPopupListActionRowDisabled(row): boolean

Defined in: base.ts:2505

Whether an action row is disabled right now.

• The library calls it from the row builders (once per row render) and again at activation. You never call it. row comes from the library.
• Default reads the entry's disabledFn; null / omitted = never disabled.

Parameters

Returns

boolean

clearSelection()

protected clearSelection(): void

Defined in: base.ts:3187

Empty the selection (invoked by the clear button). Base is a no-op; single clears to undefined, multiple to []. Goes through the normal setters, so onChange fires with the empty value. The wipe is total - chosen disabled items are cleared too (native <select> parity; unchooseAll is the enabled-only bulk op).

Returns

void

matchesQuery()

protected matchesQuery(item, query): boolean

Defined in: base.ts:3283

Per-item match predicate for the filter input.

• Default reads filterFn; else case-insensitive substring on itemToString.
• Override only when extending (subclass-wide custom matching); for a one-off match rule pass the setting.

Parameters

Returns

boolean

Subclassing: focus

findNextEnabledIndex()

protected findNextEnabledIndex(start, step, list): number

Defined in: base.ts:2285

First enabled index scanning from start (inclusive) by step (+1 / -1). Returns -1 if no enabled item lies in that direction. Used to skip disabled items during keyboard nav and initial focus.

Parameters

Returns

number

focusInitial()

protected focusInitial(): void

Defined in: base.ts:2605

Decide which item to focus when the popup opens. Default focuses the first item (or no-op if the list is empty). Override to focus the currently chosen item, last-used item, etc.

Returns

void

setFocusedIndex()

protected setFocusedIndex(index): void

Defined in: base.ts:2617

Move keyboard focus to the item at index. The value is clamped to [-1, items.length-1]; pass -1 to clear focus. Updates the focused class, aria-activedescendant, and scrolls the item into view. No-op if the clamped value equals the current focused index.

Parameters

Returns

void

focusChooseAllRow()

protected focusChooseAllRow(): boolean

Defined in: base.ts:2635

Move keyboard focus onto the choose-all row. Returns whether the row is now focused (false = none is rendered, nothing changed). The item focus is cleared (focusedIndex becomes -1). Protected so a subclass can wire its choose-all row's click to focus-then-activate (mirroring how item clicks call setFocusedIndex before onItemActivated) and use it in focusInitial (the choose-all row is the listbox's FIRST option).

Returns

boolean

computeTypeaheadClosedStartIndex()

protected computeTypeaheadClosedStartIndex(_list): number

Defined in: base.ts:2984

The option the closed-state typeahead treats as current, as an index into list, when the typed character is the keystroke that opens the popup.

• The search starts AFTER this option: the opening keystroke is always a one-character buffer, because close() and a refused open() both empty the buffer.
• Default -1: no current option, so the first match from the top wins.
• The focus focusInitial parks on open is a convenience, not a selection - it must not shift this search.
• Single mode overrides this with the chosen item's index, so a typed initial cycles past the current selection like a native <select>.
• Search internals: findTypeaheadIndex in keyboard.ts.

Parameters

Returns

number

State (protected)

settings

protected readonly settings: S

Defined in: base.ts:972

Resolved settings (defaults applied) - ONE bag for the whole hierarchy. Typed by the class's S param: a subclass that extends the settings passes its resolved extra fields through the constructor's subclassSettings param, and this field is S with no re-typing (see LLSelectSingle / LLSelectMultiple).

items

protected items: T[] = []

Defined in: base.ts:983

Current item list. Defensive copy of what setItems was given.

focusedIndex

protected focusedIndex: number = -1

Defined in: base.ts:992

Position in getVisibleItems() (the rendered list, not items) of the currently keyboard-focused item, or -1 when nothing is focused (closed popup, or no items).

changeSource

protected changeSource: LLSelectChangeSource = 'api'

Defined in: base.ts:1002

Who the change being applied right now is attributed to; the variants' onChange firing reads it. Set to 'user' by withUserChangeSource and consumed (reset to 'api') by the first onChange fired, so a nested api-driven change inside an onChange handler reports 'api'.

LLSelectMultiple

Defined in: multiple.ts:187

Multi-selection select. Clicking an item toggles its membership in the chosen-items set and keeps the popup open. Each item DOM gets aria-selected="true|false"; the popup list gets aria-multiselectable="true".

Default trigger display is a count summary ("3 / 10 selected" / "All N selected" / placeholder when empty). Pass createTriggerContentElFn (or subclass renderTriggerContent) to customise (e.g. tag chips).

Extends

• LLSelectBase<T, GroupKey, S>

Type Parameters

Selection

getChosenItems()

getChosenItems(): readonly T[]

Defined in: multiple.ts:237

Return the currently chosen items (insertion order).

Returns

readonly T[]

setChosenItems()

setChosenItems(items): void

Defined in: multiple.ts:253

Replace the entire chosen-items list.

• The input is copied, and duplicates (per compareFn) collapse to their first occurrence: the chosen items are a set.
• Fires onChange only when the new list differs from the current one. The comparison is order-sensitive: chosen order is visible state (tags render in it).
• It ignores disabled state: it can add and drop disabled items, unlike the choose* bulk ops. Assigning to a native <select> behaves the same.

Parameters

Returns

void

isChosen()

isChosen(item): boolean

Defined in: multiple.ts:279

Whether the given item is currently chosen (via compareFn).

Parameters

Returns

boolean

toggleItem()

toggleItem(item): void

Defined in: multiple.ts:309

Toggle the membership of item in the chosen-items set. Adds at the end if not present; removes if present. Fires onChange.

• While hideChosenRows is on, the popup list is rebuilt so the row leaves or re-enters it.

Parameters

Returns

void

chooseAll()

chooseAll(): void

Defined in: multiple.ts:344

Choose every enabled item.

• It acts on enabled items only, like every choose* bulk op. Bulk ops mirror clicking, and clicking cannot reach disabled items.
• Already-chosen disabled items are preserved. To change disabled items too, use setChosenItems.
• Fires onChange only when the chosen items actually change.

Returns

void

unchooseAll()

unchooseAll(): void

Defined in: multiple.ts:356

Unchoose every enabled item.

• Already-chosen disabled items are preserved. Bulk ops mirror clicking, and clicking cannot reach disabled items.
• Two paths DO drop them: the clear button, and setChosenItems([]).
• Fires onChange only when the chosen items actually change.

Returns

void

toggleAll()

toggleAll(): void

Defined in: multiple.ts:367

Toggle between "all enabled chosen" and "none chosen".

• It ignores disabled items, like every choose* bulk op.
• This is NOT the in-popup choose-all row's action. The row acts on the visible enabled subset only: see toggleAllVisible.

Returns

void

toggleAllVisible()

toggleAllVisible(): void

Defined in: multiple.ts:394

Toggle the visible enabled items between all-chosen and all-unchosen.

• This is the choose-all row's action (the chooseAllRow setting) as a public method. The row delegates here.
• Acts on exactly the items that satisfy all of the following:
  • Visible: the item is in getVisibleItems(). It matches the active filter query, and with hideChosenRows it is not chosen. With no query and without hideChosenRows, every item is visible.
  • Enabled: not disabled via itemDisabledFn, and not in a disabled group.
• If all of them are already chosen, it unchooses exactly those.
• Otherwise, it chooses the ones still missing.
• Choices outside that set (filtered-out, hidden by hideChosenRows, or disabled) are preserved either way.
• With no filter query and without hideChosenRows, the acted-on set is every enabled item, the same scope as toggleAll.
• Fires onChange only when the chosen items actually change.
• The acted-on set is computed by the overridable method getVisibleEnabledItems, shared with the choose-all row.

Returns

void

getVisibleEnabledItems()

getVisibleEnabledItems(): readonly T[]

Defined in: multiple.ts:429

Return the items a "select all" acts on: the visible, enabled ones.

• Visible: the item is in getVisibleItems(). It matches the active filter query, and with hideChosenRows it is not chosen. With no query and without hideChosenRows, every item is visible.
• Enabled: not disabled via itemDisabledFn, and not in a disabled group.
• The choose-all row (its counts, its tri-state, its click) and toggleAllVisible() both read this method.
• Use it to build your own select-all as an action row, for example in the trailing rows: count the chosen items with isChosen, write the text with getUiTranslationPack().chooseAllRowText(chosen, total), and call toggleAllVisible() from onActivate.
• Such a row is a command, not the built-in row. It has no aria-selected and no data-chosen-state, the themes give it no tri-state look, it is never the active option when the popup opens, and it stays rendered when this list is empty. For those behaviors, use chooseAllRow.
• Override it to change the subset. The tree-select demo narrows it to leaf nodes; the choose-all row and toggleAllVisible() follow the override.

Returns

readonly T[]

Items

getItems()

getItems(): readonly T[]

Defined in: base.ts:1582

Return the current item list, in data order (as passed to setItems).

• The rendered list may differ in order and content: see getVisibleItems.
• Returns the LIVE internal array, typed read-only. Do not mutate it (TS blocks it; plain-JS callers must treat it as frozen).
• Structural mutation would silently bypass chosen-state reconciliation, re-filtering, and re-render. Replace the list via setItems instead.
• Mutating item OBJECTS + rerender() is the supported in-place path.

Returns

readonly T[]

Inherited from

LLSelectBase.getItems

setItems()

setItems(items): void

Defined in: base.ts:1670

Replace the item list.

• The input is shallow-copied; later external mutation does not affect the select.
• Items MUST be unique under compareFn (it defines item identity, and the selection is a set). Duplicates render stale selection DOM; the default compareFn warns once per page, a custom compareFn is the caller's responsibility (not scanned, to keep large lists cheap).
• If the popup is open, it re-renders now. While closed, the DOM is built lazily on the next open().
• Both shipped variants re-render the trigger content from onItemsChanged (the multiple count total, custom content that reads items).
• LLSelectMultiple's triggerDisplay: 'tags' mode is opt-in; 'count' is the default.
• When triggerDisplay is 'tags', that content render is one chip per chosen item, unless createTriggerContentElFn replaces the content.
• Subclasses may reconcile chosen-state via onItemsChanged (e.g. single mode drops a chosen value that is no longer in the list).

Parameters

Returns

void

Inherited from

LLSelectBase.setItems

getVisibleItems()

getVisibleItems(): readonly T[]

Defined in: multiple.ts:459

Return the items the popup list renders, in display order.

base visible items   (LLSelectBase.getVisibleItems: gather + filter)
  |  minus chosen    (only while hideChosenRows is on; result cached)
  v
visible items        (this method's return value)

• Identical to the base behavior, minus the chosen items while hideChosenRows is on.
• While hideChosenRows is on and something is chosen, it returns a cached fresh array, not the live internal one.
• The subtraction recomputes only when the base list or the chosen set changed. Calls in between return the same cached array.

Returns

readonly T[]

Overrides

LLSelectBase.getVisibleItems

Open & close

open()

open(): void

Defined in: base.ts:1363

Open the popup. Builds item elements lazily, attaches the positioner (which auto-closes if the trigger is scrolled out of view), wires the outside-click handler, and moves keyboard focus into the item list. No-op if already open.

Returns

void

Inherited from

LLSelectBase.open

close()

close(): void

Defined in: base.ts:1447

Close the popup. Detaches positioner and outside-click listener, clears the item DOM, and resets focused-item state. No-op if already closed.

Focus return is decided automatically: when DOM focus is still inside the popup at the moment of close - the filter input (Esc on an empty filter, a single-select pick, an outside press on a non-focusable area) or a focusable control the app placed in a header / footer slot (Esc there, or close() called from its own click) - focus is returned to the trigger. Tab-away and outside clicks on focusable elements have already moved focus elsewhere, so we leave it alone.

Returns

void

Inherited from

LLSelectBase.close

toggle()

toggle(): void

Defined in: base.ts:1552

Open if closed, close if open.

Returns

void

Inherited from

LLSelectBase.toggle

isOpened()

isOpened(): boolean

Defined in: base.ts:1568

Whether the popup is currently open.

• Pairs with isDisabled() (state read via method).
• The same state is mirrored on the DOM as CSS hooks: data-state="open|closed" on the trigger, classIdMap.openClass on the root.

Returns

boolean

Inherited from

LLSelectBase.isOpened

Trigger

setPlaceholder()

setPlaceholder(placeholder): void

Defined in: base.ts:1643

Replace the trigger placeholder text at runtime. It is one of the two settings with a runtime setter (the other is setUiTranslationPack); both are copy. The rule: LLSelectBaseSettings.

• null = fall back to the pack default (uiTranslationPack.triggerPlaceholder), mirroring an unset constructor placeholder. An explicit value keeps winning over later setUiTranslationPack calls, exactly like the constructor input.
• Takes effect immediately. Visible only while nothing is chosen - the placeholder never renders otherwise (the trigger is still re-rendered, which also refreshes the hidden accessible-value mirror).

Parameters

Returns

void

Inherited from

LLSelectBase.setPlaceholder

Filtering

getFilterQuery()

getFilterQuery(): string

Defined in: base.ts:3271

Return the filter input's current query, exactly the string passed to filterFn.

• It is '' while the popup is closed, the filter is inactive, or the input is empty.
• It resets on close: each open cycle starts empty.

Returns

string

Inherited from

LLSelectBase.getFilterQuery

Disabling

setDisabled()

setDisabled(value): void

Defined in: base.ts:1706

Enable or disable the whole control. Disabled: the trigger gets aria-disabled + data-disabled (never the native disabled attribute, which would suppress the hover / focus events a tooltip needs), opening is blocked, an open popup closes, and the trigger leaves the tab order unless focusableWhenDisabled is set. Stored as state, mirroring setItems / setChosenItems (this design keeps mutable state out of settings).

Parameters

Returns

void

Inherited from

LLSelectBase.setDisabled

isDisabled()

isDisabled(): boolean

Defined in: base.ts:1717

Whether the whole control is disabled.

Returns

boolean

Inherited from

LLSelectBase.isDisabled

i18n

getUiTranslationPack()

getUiTranslationPack(): Readonly<LLSelectUiTranslationPack>

Defined in: base.ts:1595

Return the resolved UI strings: the built-in English defaults merged with the uiTranslationPack setting.

• Reuse these in your own UI instead of keeping a second translation source. For example, a tag remove button tooltip: sel.getUiTranslationPack().tagRemoveButtonAriaLabel(label).
• Returns the LIVE object. Treat it as immutable, like getItems.

Returns

Readonly<LLSelectUiTranslationPack>

Inherited from

LLSelectBase.getUiTranslationPack

setUiTranslationPack()

setUiTranslationPack(uiTranslationPack): void

Defined in: base.ts:1616

Replace the UI-translation pack at runtime, so switching language needs no re-new.

• One of the two settings with a runtime setter (the other is setPlaceholder); both are copy. The rule: LLSelectBaseSettings.
• The pack is resolved exactly like the constructor's: merged over the built-in English pack, NOT over the previously set pack.
• An explicit constructor placeholder keeps winning over the new pack's triggerPlaceholder.
• Re-renders the trigger and the open popup.
• Also re-applies the pack-owned attributes rerender() cannot reach: the filter input placeholder and its fallback aria-label.
• The clear button needs no such step: rerender() rebuilds it, and the rebuild reads the new pack - unless a createTriggerClearButtonEl override returns the previous element, which then owns the label.

Parameters

Returns

void

Inherited from

LLSelectBase.setUiTranslationPack

Lifecycle

rerender()

rerender(): void

Defined in: base.ts:1517

Rebuild the trigger and (while open) the popup list from current state.

• Use it after mutating item OBJECTS in place (e.g. users[0].name = 'X'). The library cannot detect that on its own.
• It re-derives the display order (the gatherGroups gather).
• While the filter is active, it re-runs the filter against the current item text.
• The refresh is purely visual: it does NOT fire onChange and does NOT run onItemsChanged.
• Orchestrator: composes renderTrigger + renderPopupList; touches no DOM directly.

Returns

void

Inherited from

LLSelectBase.rerender

destroy()

destroy(): void

Defined in: base.ts:1537

Tear down the instance: close the popup (which detaches every document / window listener and the positioner), unwire labelEl (click listener removed, a minted id removed), remove the library's class and inline styles from the caller's mount element, and empty it. Idempotent. The instance must not be used afterwards.

• REQUIRED before discarding an instance that might be OPEN (framework wrappers: call this on unmount) - skipping it there leaks the outside-click / focusout / scroll / resize listeners.
• Discarding a CLOSED instance without destroy() leaks nothing; it only leaves the root class and overflow-anchor style on the mount.

Returns

void

Inherited from

LLSelectBase.destroy

Constructor

new LLSelectMultiple<T, GroupKey, S>(targetEl, settings?): LLSelectMultiple<T, GroupKey, S>

Defined in: multiple.ts:207

Build the control inside targetEl.

• Settings are resolved once here; missing fields get defaults.
• They are frozen afterwards, except placeholder and uiTranslationPack, which have runtime setters; the rule is at LLSelectBaseSettings.
• This plain form infers T from a typed callback in settings whose signature contains T (itemToStringFn: (u: User) => ...). With no such callback, pass T explicitly: new LLSelectMultiple<string>(...).

Parameters

Returns

LLSelectMultiple<T, GroupKey, S>

Overrides

LLSelectBase.constructor

Constructor

new LLSelectMultiple<T, GroupKey, S>(targetEl, settings?, subclassSettings?): LLSelectMultiple<T, GroupKey, S>

Defined in: multiple.ts:213

Subclass form. subclassSettings is the typed pass-through for subclasses that extend the settings bag further; see LLSelectBase's S param.

Parameters

Returns

LLSelectMultiple<T, GroupKey, S>

Overrides

LLSelectBase<T, GroupKey, S>.constructor

DOM elements

rootEl

readonly rootEl: HTMLElement

Defined in: base.ts:875

The caller-passed mount element, now decorated as the select's root. Library does not replace this node, so the caller's original reference, id, and data-* attributes stay valid.

Inherited from

LLSelectBase.rootEl

triggerEl

readonly triggerEl: HTMLElement

Defined in: base.ts:885

The interactive trigger element. Receives focus, click, and keydown events; carries aria-expanded, aria-controls, and data-state="open|closed". Its role depends on the filter mode: combobox while the filter is inactive (it then also hosts aria-activedescendant) and button while a filterable popup is open (the filter input hosts aria-activedescendant). See docs/llm/A11Y.md.

Inherited from

LLSelectBase.triggerEl

triggerContentEl

readonly triggerContentEl: HTMLElement

Defined in: base.ts:892

Inner span inside the trigger where text/tags are written. Subclasses' renderTriggerContent writes here so the sibling arrow slot is preserved across re-renders.

Inherited from

LLSelectBase.triggerContentEl

popupEl

readonly popupEl: HTMLElement

Defined in: base.ts:909

The outer popup wrapper. Has no ARIA role itself - it just hosts the popup chrome (future: filter input, toggle-all control) and the inner popupListEl. Hidden via the hidden attribute when closed; positioned via inline styles by the positioner when open.

Inherited from

LLSelectBase.popupEl

popupListEl

readonly popupListEl: HTMLElement

Defined in: base.ts:917

The inner element with role="listbox", holding the item children. Sits inside popupEl so siblings (filter input, toggle-all) can live above it without violating ARIA's "listbox children must be options" rule. The trigger's aria-controls points to this element.

Inherited from

LLSelectBase.popupListEl

popupHeaderEl

readonly popupHeaderEl: HTMLElement | null

Defined in: base.ts:925

The pinned header container between the filter input and the listbox, or null when no header content was built. No ARIA role; outside the scroll area. Built once in the constructor (createPopupHeaderEl) and kept until destroy(); the library never rebuilds or moves it.

Inherited from

LLSelectBase.popupHeaderEl

popupFooterEl

readonly popupFooterEl: HTMLElement | null

Defined in: base.ts:932

The pinned footer container at the bottom of the popup, after the no-results message, or null when no footer content was built. Same lifecycle as popupHeaderEl.

Inherited from

LLSelectBase.popupFooterEl

popupListPinnedLeadingRowsEl

readonly popupListPinnedLeadingRowsEl: HTMLElement | null

Defined in: base.ts:950

The wrapper around the pinned leading rows, or null.

• Built once in the constructor when popupListLeadingRowsPinned is true; null otherwise.
• A div with role="presentation" and class popupListPinnedLeadingRowsClass; the library sets position: sticky and top: 0 on it inline.
• In the listbox only while the leading rows exist. The library moves it in and out on every list render. Its classes are yours to change after new.
• data-edge-to-items is set on every list render: "true" when that render lists items, "false" when it lists none; absent before the first render.
• It is a CSS hook for the themes: they draw the block's edge line only when it is true, so two blocks that touch draw no line between them.

Inherited from

LLSelectBase.popupListPinnedLeadingRowsEl

popupListPinnedTrailingRowsEl

readonly popupListPinnedTrailingRowsEl: HTMLElement | null

Defined in: base.ts:957

The wrapper around the pinned trailing rows, or null.

• Same contract as popupListPinnedLeadingRowsEl, for popupListTrailingRowsPinned, with bottom: 0.

Inherited from

LLSelectBase.popupListPinnedTrailingRowsEl

classIdMap

readonly classIdMap: LLSelectClassIdMap

Defined in: base.ts:962

Resolved class names and ids for this instance.

Inherited from

LLSelectBase.classIdMap

triggerValueEl

protected readonly triggerValueEl: HTMLElement

Defined in: base.ts:901

Hidden root-level span (sibling of the trigger) mirroring the current value as plain text. Kept in sync by commitTriggerContentToDom; referenced by the filterable-mode aria-labelledby chain (see classIdMap.triggerValueId). Outside the trigger so triggerEl.textContent stays exactly the visible content.

Inherited from

LLSelectBase.triggerValueEl

Subclassing: reactions

onOpened()

protected onOpened(): void

Defined in: base.ts:1753

Subclass hook: called once after the popup finishes opening. Default no-op. The onOpen setting fires alongside this (both run) - hook for subclass logic, setting for consumer notification.

Returns

void

Inherited from

LLSelectBase.onOpened

onClosed()

protected onClosed(): void

Defined in: base.ts:1758

Subclass hook: called once after the popup finishes closing. Pairs with the onClose setting (both run).

Returns

void

Inherited from

LLSelectBase.onClosed

onChosenChanged()

protected onChosenChanged(): void

Defined in: base.ts:1765

Subclass hook: called after the chosen state actually changed, right before the variant's onChange setting fires (hook first, both run - same pairing as onOpened / onClosed). Default no-op.

Returns

void

Inherited from

LLSelectBase.onChosenChanged

onPopupListActionRowActivated()

protected onPopupListActionRowActivated(row): void

Defined in: base.ts:2522

Subclass hook: an action row was activated.

• The library calls it on Enter, on Space while the filter is inactive, and on click, after the disabled re-check, as a user change. You never call it. row comes from the library: the activated entry.
• Default calls the entry's onActivate. The library changes nothing else: choosing and closing are the entry's job.
• Override to react before or after: do your work, then call super.onPopupListActionRowActivated(row). Without that call the entry's onActivate never runs.

Parameters

Returns

void

Inherited from

LLSelectBase.onPopupListActionRowActivated

withUserChangeSource()

protected withUserChangeSource<R>(fn): R

Defined in: base.ts:2582

Run fn with chosen-state changes attributed to the user. The library wraps exactly its pointer / keyboard entry points with it - option activation, the tag remove button, the clear button, the choose-all row; everything else reports 'api'.

Type Parameters

Parameters

Returns

R

Inherited from

LLSelectBase.withUserChangeSource

onItemActivated()

protected onItemActivated(item): void

Defined in: multiple.ts:633

Toggle on click. Multi mode keeps the popup open.

Parameters

Returns

void

Overrides

LLSelectBase.onItemActivated

onChooseAllRowActivated()

protected onChooseAllRowActivated(): void

Defined in: multiple.ts:711

Activate the choose-all row: delegates to toggleAllVisible.

Returns

void

Overrides

LLSelectBase.onChooseAllRowActivated

onItemsChanged()

protected onItemsChanged(): void

Defined in: multiple.ts:745

Re-match the chosen entries against the new list after setItems.

• Entries the list no longer holds (by compareFn) are dropped and onChange fires for the drop.
• When the list holds a compareFn-equal but DIFFERENT object (track by style reload: same key, fresh fields), the stored reference is swapped to the list's object. A reference swap is not a logical change, so it does not fire onChange.
• The trigger content re-renders after every setItems, swap or not.
• Why: the count summary shows the list total, and a custom createTriggerContentElFn receives items.
• The arrow re-renders only when a chosen entry is dropped, because that runs the whole trigger.
• triggerDisplay: 'tags' is opt-in; 'count' is the default.
• When triggerDisplay is 'tags', that render is one chip per chosen item per setItems, unless createTriggerContentElFn replaces the content.
• That cost is acceptable: setItems is a bulk call.

Returns

void

Overrides

LLSelectBase.onItemsChanged

Subclassing: rendering

renderTrigger()

protected renderTrigger(): void

Defined in: base.ts:1810

Orchestrator: composes the clear-button rebuild + renderTriggerContent + renderTriggerArrow to (re)build the whole trigger from state; touches no DOM directly. Subclasses normally override renderTriggerContent, not this.

• Runs on every change of the chosen value, the placeholder or the pack.
• rerender() runs it too.
• While clearable is on, the first run builds the clear button and every later run swaps it for whatever createTriggerClearButtonEl returns: a fresh button from the base implementation, like the arrow. An override may return the previous element; it is then kept in place.
• If the button is rebuilt and the old one held focus - on it or inside its icon - the rebuilt BUTTON gets it.
• If the builder returned the same element, nothing was rebuilt, and focus goes back to the node that held it, if that node is still inside the button and can take focus; otherwise focus stays on the button.
• setItems runs renderTriggerContent alone, because only the content reads the list (the multiple count total, a custom createTriggerContentElFn's items).
• A setItems that drops the chosen entry runs the whole trigger.
• Runs once from the LLSelectSingle / LLSelectMultiple constructor, right after super().
• On that first run a FURTHER subclass's own fields are still undefined: JS runs a subclass's field initializers only after its super constructor returns (virtual-call-in-constructor). An override of a trigger method (renderTriggerContent, or a create*El it calls) that reads such a field sees undefined there.
• The recipe: put construction-time configuration in the typed subclassSettings constructor param. this.settings is complete before any construction code runs.
• For genuine instance state, tolerate defaults during construction, or call rerender() at the end of your own constructor.
• The popup-list methods do NOT run here; they wait for open(). See DESIGN.md "Customization model".

Returns

void

Inherited from

LLSelectBase.renderTrigger

commitTriggerContentToDom()

protected commitTriggerContentToDom(content, plainTextValue?): void

Defined in: base.ts:1833

Write the trigger's content slot (triggerContentEl), replacing whatever was there; the sibling arrow slot is untouched. The single DOM-writing primitive behind every renderTriggerContent path.

• string -> set as textContent (plain text, NOT parsed as HTML). Used for the default placeholder / itemToString text / count summary.
• HTMLElement -> inserted as-is via replaceChildren; caller owns the node. Used for whatever the createTriggerContentElFn setting returned.
• Also mirrors the value into the hidden triggerValueEl (the accessible name source): the string itself, else plainTextValue, else the element's textContent. Pass plainTextValue whenever the element contains labelled controls (tag remove buttons) or icon-only content - the mirror is what AT announces as the field's value. Called by renderTriggerContent - the base default and the LLSelectSingle / LLSelectMultiple overrides.

Parameters

Returns

void

Inherited from

LLSelectBase.commitTriggerContentToDom

syncEmptyStateToDom()

protected syncEmptyStateToDom(): void

Defined in: base.ts:1850

Mirror the empty/filled state onto the trigger's data-empty attribute ("true" when isEmpty(), else "false"). A CSS / AT styling hook, independent of the rendered content. Called by the subclass renderTriggerContent overrides.

Returns

void

Inherited from

LLSelectBase.syncEmptyStateToDom

createTriggerArrowContentEl()

protected createTriggerArrowContentEl(state): HTMLElement | SVGElement | null

Defined in: base.ts:1896

Trigger arrow element for the given open state.

• Default reads createTriggerArrowContentElFn; null (setting unset, or returned for a state) = no arrow for that state.
• Override only when extending; for one-off arrows pass the setting. Mirrors createTriggerClearButtonEl / createItemContentEl.

Parameters

Returns

HTMLElement | SVGElement | null

Inherited from

LLSelectBase.createTriggerArrowContentEl

renderPopupList()

protected renderPopupList(): void

Defined in: base.ts:1929

Orchestrator: composes createItemEl (build) + computePopupSegments + commitPopupSegmentsToDom (write) to rebuild the popup list from getVisibleItems(); touches no DOM directly. Called by open() and by setItems() while open. Also clamps focusedIndex if the list shrank and re-applies focus visuals.

• Extend it by wrapping: override, do your work before or after, then call super.renderPopupList(). The ui-select bridge frees its row scopes this way. Or override one of the methods it calls through this: createItemEl, createPopupListChooseAllRowEl, createPopupListLeadingActionRowEl / createPopupListTrailingActionRowEl, itemToGroupKey, getVisibleItems.
• Its other internals stay private on purpose. They re-establish the itemEls[i] <-> getVisibleItems()[i] alignment as one unit, so no subclass can leave keyboard nav or aria-activedescendant half-synced.

Returns

void

Inherited from

LLSelectBase.renderPopupList

createGroupEl()

protected createGroupEl(key, index, items, itemEls): HTMLElement

Defined in: base.ts:2064

Build the whole DOM element for one group container.

• The library calls it, once per group of the current render, on every list render. You never call it yourself.
• All four params come from the library. Forward them to super unchanged.
• index is the group's position among this render's groups, counted from 0. It only mints the group id. It is not an identity: it changes whenever the visible list changes.
• To change only the label's content, do not override this. Pass the createGroupLabelContentElFn setting instead.
• To change the element itself, override it, call super.createGroupEl(...), and edit the returned element. Keep the role and aria-label the base set.
• Internals: the base sets the id, role="group" named by groupKeyToString (aria-label), an aria-hidden visible label element filled from createGroupLabelContentEl (else the plain label text), then the group's item elements; aria-disabled + data-disabled when the group is disabled.

Parameters

Returns

HTMLElement

Inherited from

LLSelectBase.createGroupEl

createGroupLabelContentEl()

protected createGroupLabelContentEl(key, itemsInGroup): HTMLElement | null

Defined in: base.ts:2098

Group label -> its visible content element (icon / count badge / rich markup). Mirrors createItemContentEl.

• Default reads createGroupLabelContentElFn, else null so createGroupEl uses plain text from groupKeyToString.
• The group's accessible name stays groupKeyToString (container aria-label); this fills only the visible, aria-hidden label content.
• Override only when extending; for one-off rich labels pass the setting.

Parameters

Returns

HTMLElement | null

Inherited from

LLSelectBase.createGroupLabelContentEl

replacePopupListItemElInDom()

protected replacePopupListItemElInDom(item): void

Defined in: base.ts:2112

Re-render a single item's element in place instead of rebuilding the whole popup list. The DOM work is O(1) regardless of list size, so flipping one selection in a 10k-item list does not recreate 10k nodes (the lookup to find the item is O(n), but that is a cheap comparison loop next to DOM mutation). No-op if the popup is closed or the item is not in the current list. Used by multi-select toggle.

Parameters

Returns

void

Inherited from

LLSelectBase.replacePopupListItemElInDom

createItemContentEl()

protected createItemContentEl(item): HTMLElement | null

Defined in: base.ts:2222

Item -> the visible content of its list row (icon + text etc.).

• Default reads createItemContentElFn, else null so createItemEl uses the plain-text default from itemToString.
• Override only when extending; for one-off rich content pass the setting.

Parameters

Returns

HTMLElement | null

Inherited from

LLSelectBase.createItemContentEl

createPopupListLeadingActionRowEl()

protected createPopupListLeadingActionRowEl(row, index): HTMLElement

Defined in: base.ts:2427

Build the whole DOM element for one leading action row (above the items).

• The library calls it, once per entry of popupListLeadingActionRows, on every list render and after every chosen change. You never call it.
• Both params come from the library. Forward them to super unchanged. row is the entry; index is its position in that array, counted from 0, used to mint the id. It is not an identity.
• To change only what the row shows, do not override this: give the entry a createContentElFn.
• To change the element itself, override it, call super.createPopupListLeadingActionRowEl(row, index), and edit the returned element. Keep the id and role; put no focusable control inside.
• Internals: a div with role="option", the id <listbox id>-action-row-leading<index>, itemClass plus popupListActionRowClass, the visible content from createPopupListActionRowContentEl (else textContent from textFn), aria-label = textFn() when the content is custom, and either aria-disabled plus the disabled class (isPopupListActionRowDisabled) or a click handler that focuses the row, then runs onPopupListActionRowActivated. No aria-selected: a command has no selected state.

Parameters

Returns

HTMLElement

Inherited from

LLSelectBase.createPopupListLeadingActionRowEl

createPopupListTrailingActionRowEl()

protected createPopupListTrailingActionRowEl(row, index): HTMLElement

Defined in: base.ts:2450

Build the whole DOM element for one trailing action row (below the items).

• The library calls it, once per entry of popupListTrailingActionRows, on every list render and after every chosen change. You never call it.
• Both params come from the library. Forward them to super unchanged. row is the entry; index is its position in that array, counted from 0, used to mint the id. It is not an identity.
• To change only what the row shows, do not override this: give the entry a createContentElFn.
• To change the element itself, override it, call super.createPopupListTrailingActionRowEl(row, index), and edit the returned element. Keep the id and role; put no focusable control inside.
• Internals: identical to createPopupListLeadingActionRowEl except the id, <listbox id>-action-row-trailing<index>.

Parameters

Returns

HTMLElement

Inherited from

LLSelectBase.createPopupListTrailingActionRowEl

createPopupListActionRowContentEl()

protected createPopupListActionRowContentEl(row): HTMLElement | null

Defined in: base.ts:2493

An action row's visible content element.

• The library calls it from the row builders, once per row render. You never call it. row comes from the library.
• Default reads the entry's createContentElFn; null (unset, or returned) = plain text from textFn.
• Override only when extending; for one-off content give the entry a createContentElFn.

Parameters

Returns

HTMLElement | null

Inherited from

LLSelectBase.createPopupListActionRowContentEl

replacePopupListActionRowElsInDom()

protected replacePopupListActionRowElsInDom(): void

Defined in: base.ts:2538

Rebuild every rendered action row in place, so textFn / disabledFn reflect the current state; the row holding the active option keeps it.

• The library calls it after every chosen change, right after onChange fired (a row's text may read what the handler wrote). Subclasses may call it after a state change of their own.
• No-op while closed, or when both row arrays are empty - instances without rows pay nothing.
• O(rows) DOM work; the item rows are untouched.

Returns

void

Inherited from

LLSelectBase.replacePopupListActionRowElsInDom

replaceChooseAllRowElInDom()

protected replaceChooseAllRowElInDom(): void

Defined in: base.ts:2652

Rebuild the choose-all row in place (tri-state / text refresh) without touching the item elements - O(1) DOM work, mirroring replacePopupListItemElInDom. Falls back to a full renderPopupList when the row becomes inapplicable (builder returns null). No-op while closed or when no choose-all row is rendered.

Returns

void

Inherited from

LLSelectBase.replaceChooseAllRowElInDom

createTriggerClearButtonEl()

protected createTriggerClearButtonEl(): HTMLElement

Defined in: base.ts:3047

Build the clear (x) button for the clearable trigger slot.

• The library owns the button, its click (stops propagation so it never toggles the popup, then clearSelection; a no-op while the control is disabled) and its aria-label (text from uiTranslationPack.triggerClearButtonAriaLabel).
• createTriggerClearButtonContentElFn optionally fills the icon; else the theme's CSS glyph draws it.
• The theme hides the button via data-empty while nothing is chosen.
• It runs on every trigger render (renderTrigger).
• The first run builds the button.
• For LLSelectSingle / LLSelectMultiple and their subclasses, that first run is the variant constructor's render, right after super(), so it happens before a FURTHER subclass's field initializers.
• A direct LLSelectBase subclass gets the button on its first trigger render (its own renderTrigger() call, or rerender() / setPlaceholder); until then the trigger is unrendered and there is no button.
• Every later run (a value change, setPlaceholder, setUiTranslationPack, rerender()) swaps the button in place, unless this method returns the previous element - then it stays in place.
• The base implementation returns a fresh element each run, so, like the arrow, nothing put on it from outside survives a render; customize it here.
• An override that returns the same element every time owns everything the rebuild would otherwise refresh on it, including its aria-label after setUiTranslationPack.
• An override that reads subclass fields calls rerender() at the end of its constructor, like every other trigger method.

Returns

HTMLElement

Inherited from

LLSelectBase.createTriggerClearButtonEl

createTriggerClearButtonContentEl()

protected createTriggerClearButtonContentEl(): HTMLElement | SVGElement | null

Defined in: base.ts:3174

Clear button's visible content (its x icon).

• Default reads createTriggerClearButtonContentElFn; null (setting unset, or returned) = no icon - the theme's CSS glyph draws the x.
• Override only when extending; for one-off icons pass the setting.

Returns

HTMLElement | SVGElement | null

Inherited from

LLSelectBase.createTriggerClearButtonContentEl

createPopupListNoResultsContentEl()

protected createPopupListNoResultsContentEl(query): HTMLElement | null

Defined in: base.ts:3356

The no-results message's visible content (rich empty-state).

• Default reads createPopupListNoResultsContentElFn; null (setting unset, or returned) = plain text from uiTranslationPack.popupListNoResults.
• Override only when extending; for one-off content pass the setting.

Parameters

Returns

HTMLElement | null

Inherited from

LLSelectBase.createPopupListNoResultsContentEl

createPopupHeaderEl()

protected createPopupHeaderEl(): HTMLElement | null

Defined in: base.ts:3376

Build the pinned header container between the filter input and the listbox.

• The library calls it once, inside the constructor. You never call it.
• It takes no params. The default asks createPopupHeaderContentEl for content; null content = no container, and popupHeaderEl stays null.
• To supply content without subclassing, pass createPopupHeaderContentElFn.
• To change the container itself, override it: call super.createPopupHeaderEl() and edit the returned element, or return your own div. Returning non-null builds the slot even without the setting. Keep it role-free: it is not part of the listbox.
• Internals: the base builds a div with classIdMap.popupHeaderClass and inline flex: none (the popup is a flex column and only the listbox may flex), then appends the content.

Returns

HTMLElement | null

Inherited from

LLSelectBase.createPopupHeaderEl

createPopupHeaderContentEl()

protected createPopupHeaderContentEl(): HTMLElement | null

Defined in: base.ts:3390

The pinned header's content element.

• The library calls it once, from createPopupHeaderEl, inside the constructor. You never call it.
• Default calls createPopupHeaderContentElFn with a LLSelectConstructionContext; null (setting unset, or returned) = no header at all.
• Override only when extending; for one-off content pass the setting.

Returns

HTMLElement | null

Inherited from

LLSelectBase.createPopupHeaderContentEl

createPopupFooterEl()

protected createPopupFooterEl(): HTMLElement | null

Defined in: base.ts:3410

Build the pinned footer container at the bottom of the popup.

• The library calls it once, inside the constructor. You never call it.
• It takes no params. The default asks createPopupFooterContentEl for content; null content = no container, and popupFooterEl stays null.
• To supply content without subclassing, pass createPopupFooterContentElFn.
• To change the container itself, override it: call super.createPopupFooterEl() and edit the returned element, or return your own div. Returning non-null builds the slot even without the setting. Keep it role-free: it is not part of the listbox.
• Internals: the base builds a div with classIdMap.popupFooterClass and inline flex: none (only the listbox may flex), then appends the content.

Returns

HTMLElement | null

Inherited from

LLSelectBase.createPopupFooterEl

createPopupFooterContentEl()

protected createPopupFooterContentEl(): HTMLElement | null

Defined in: base.ts:3424

The pinned footer's content element.

• The library calls it once, from createPopupFooterEl, inside the constructor. You never call it.
• Default calls createPopupFooterContentElFn with a LLSelectConstructionContext; null (setting unset, or returned) = no footer at all.
• Override only when extending; for one-off content pass the setting.

Returns

HTMLElement | null

Inherited from

LLSelectBase.createPopupFooterContentEl

renderTriggerContent()

protected renderTriggerContent(): void

Defined in: multiple.ts:487

Orchestrator: composes syncEmptyStateToDom + commitTriggerContentToDom to (re)build the trigger from state; touches no DOM directly. Default text is a count summary; override (or pass the createTriggerContentElFn setting) to display tags / custom markup / etc.

• If 0 items are chosen, the text is placeholder.
• If n > 0, the text is uiTranslationPack.triggerCountSummary(n, total) (English default: "n / total selected", or "All n selected" when all are chosen).

Returns

void

Overrides

LLSelectBase.renderTriggerContent

createTagsEl()

protected createTagsEl(): HTMLElement

Defined in: multiple.ts:514

Build the tag-list element for 'tags' mode: one chip per chosen item. Override for full control of the chip strip (the trigger-level equivalent of overriding createItemEl).

Returns

HTMLElement

createTagEl()

protected createTagEl(item): HTMLElement

Defined in: multiple.ts:532

Build one removable tag chip: its content (from createTagContentEl, else plain itemToString) plus its remove (x) button (from createTagRemoveButtonEl). A chip whose item is effectively disabled gets aria-disabled="true" + tagDisabledClass, and its x turns inert - mirroring a disabled option row. Override for full control of the chip container; override the two sub-parts for content-only / remove-button-only changes.

Parameters

Returns

HTMLElement

createTagRemoveButtonEl()

protected createTagRemoveButtonEl(item): HTMLElement

Defined in: multiple.ts:564

Build one chip's remove (x) button. The library owns the button + its click (stopPropagation so it never toggles the popup, then toggleItem; a no-op while the whole control OR the item itself is disabled) + tabindex="-1" + aria-label (from itemToTagRemoveButtonAriaLabel). An effectively-disabled item's button also gets aria-disabled="true". createTagRemoveButtonContentElFn optionally fills the icon, else the theme's CSS glyph. Mirrors the clear button's createTriggerClearButtonEl. Override for full control of the button element.

Parameters

Returns

HTMLElement

createTagRemoveButtonContentEl()

protected createTagRemoveButtonContentEl(item): HTMLElement | SVGElement | null

Defined in: multiple.ts:594

One chip's remove-button visible content (its x icon). Mirrors createTriggerClearButtonContentEl.

• Default reads createTagRemoveButtonContentElFn; null (setting unset, or returned) = no icon - the theme's CSS glyph draws the x.
• Override only when extending; for one-off icons pass the setting.

Parameters

Returns

HTMLElement | SVGElement | null

createTagContentEl()

protected createTagContentEl(item): HTMLElement | null

Defined in: multiple.ts:605

Per-chip visible content in 'tags' mode. Mirrors createItemContentEl. Default reads createTagContentElFn, else null so createTagEl falls back to plain text from itemToString.

Parameters

Returns

HTMLElement | null

createPopupListChooseAllRowEl()

protected createPopupListChooseAllRowEl(): HTMLElement | null

Defined in: multiple.ts:654

Build the choose-all row (chooseAllRow setting) as the listbox's leading role="option" row: data-chosen-state="none|some|all" (a CSS styling hook), aria-selected only when ALL visible enabled items are chosen, accessible name + visible text from uiTranslationPack.chooseAllRowText(chosenCount, totalCount) over the visible enabled subset. null when the setting is off or nothing is actionable.

Returns

HTMLElement | null

Overrides

LLSelectBase.createPopupListChooseAllRowEl

createChooseAllRowContentEl()

protected createChooseAllRowContentEl(chosenState, chosenCount, totalCount): HTMLElement | null

Defined in: multiple.ts:698

The choose-all row's visible content (rich tri-state). Mirrors createItemContentEl.

• Default reads createChooseAllRowContentElFn; null (setting unset, or returned) = the default content: plain text from uiTranslationPack.chooseAllRowText.
• Override only when extending; for one-off content pass the setting.

Parameters

Returns

HTMLElement | null

createItemEl()

protected createItemEl(item, index): HTMLElement

Defined in: multiple.ts:719

Mark each item with aria-selected reflecting its chosen state.

Parameters

Returns

HTMLElement

Overrides

LLSelectBase.createItemEl

Subclassing: semantics

itemToString()

protected itemToString(item): string

Defined in: base.ts:2210

Map an item to its display string. The library calls this everywhere it needs an item's text: list rows, the single trigger text, default filter.

• Default reads the itemToStringFn setting, else String(item).
• Configure via itemToStringFn (no subclass needed).
• Override only when extending (a new select type); your override replaces the default. For HTML content, subclass createItemEl.

Parameters

Returns

string

Inherited from

LLSelectBase.itemToString

isItemEffectivelyDisabled()

protected isItemEffectivelyDisabled(item): boolean

Defined in: base.ts:2236

Whether item is effectively disabled - by itemDisabledFn, or because its group is disabled (groupDisabledFn). Group-disabled layers on top, so every item-disabled behavior (no selection, keyboard skip, aria) covers grouped items with no extra code. False when neither applies. The whole-control disabled state (isDisabled()) is a separate layer, not part of this answer.

Parameters

Returns

boolean

Inherited from

LLSelectBase.isItemEffectivelyDisabled

itemToGroupKey()

protected itemToGroupKey(item): GroupKey | null

Defined in: base.ts:2255

Map an item to its group key, or null when it belongs to no group. The authoritative method: rendering, the gatherGroups gather, and the disabled layer all resolve keys through this method, so an override drives them all - returning keys turns grouping on even with the setting unset (all-null keys = flat list). An override reading external state must call rerender() after that state changes (same contract as mutating item objects).

• Default reads itemToGroupKeyFn, else null (grouping off).
• Override only when extending; configure via the setting.

Parameters

Returns

GroupKey | null

Inherited from

LLSelectBase.itemToGroupKey

groupKeyToString()

protected groupKeyToString(key): string

Defined in: base.ts:2265

Map a group key to its label display text.

• Default reads groupKeyToStringFn, else String(key).

Parameters

Returns

string

Inherited from

LLSelectBase.groupKeyToString

isGroupDisabled()

protected isGroupDisabled(key): boolean

Defined in: base.ts:2274

Whether the whole group key is disabled per groupDisabledFn (false when unset).

Parameters

Returns

boolean

Inherited from

LLSelectBase.isGroupDisabled

isPopupListActionRowDisabled()

protected isPopupListActionRowDisabled(row): boolean

Defined in: base.ts:2505

Whether an action row is disabled right now.

• The library calls it from the row builders (once per row render) and again at activation. You never call it. row comes from the library.
• Default reads the entry's disabledFn; null / omitted = never disabled.

Parameters

Returns

boolean

Inherited from

LLSelectBase.isPopupListActionRowDisabled

matchesQuery()

protected matchesQuery(item, query): boolean

Defined in: base.ts:3283

Per-item match predicate for the filter input.

• Default reads filterFn; else case-insensitive substring on itemToString.
• Override only when extending (subclass-wide custom matching); for a one-off match rule pass the setting.

Parameters

Returns

boolean

Inherited from

LLSelectBase.matchesQuery

itemToTagRemoveButtonAriaLabel()

protected itemToTagRemoveButtonAriaLabel(item): string

Defined in: multiple.ts:617

Item -> its remove button's accessible name in 'tags' mode.

• Default: uiTranslationPack.tagRemoveButtonAriaLabel(itemToString(item)).
• Override only when extending (e.g. a name from another item field); per-locale text goes through the uiTranslationPack setting.

Parameters

Returns

string

isEmpty()

protected isEmpty(): boolean

Defined in: multiple.ts:625

No selection iff the chosen set is empty. Drives the trigger's data-empty.

Returns

boolean

Overrides

LLSelectBase.isEmpty

clearSelection()

protected clearSelection(): void

Defined in: multiple.ts:641

Clear button empties the chosen-items set to [].

Returns

void

Overrides

LLSelectBase.clearSelection

Subclassing: focus

findNextEnabledIndex()

protected findNextEnabledIndex(start, step, list): number

Defined in: base.ts:2285

First enabled index scanning from start (inclusive) by step (+1 / -1). Returns -1 if no enabled item lies in that direction. Used to skip disabled items during keyboard nav and initial focus.

Parameters

Returns

number

Inherited from

LLSelectBase.findNextEnabledIndex

setFocusedIndex()

protected setFocusedIndex(index): void

Defined in: base.ts:2617

Move keyboard focus to the item at index. The value is clamped to [-1, items.length-1]; pass -1 to clear focus. Updates the focused class, aria-activedescendant, and scrolls the item into view. No-op if the clamped value equals the current focused index.

Parameters

Returns

void

Inherited from

LLSelectBase.setFocusedIndex

focusChooseAllRow()

protected focusChooseAllRow(): boolean

Defined in: base.ts:2635

Move keyboard focus onto the choose-all row. Returns whether the row is now focused (false = none is rendered, nothing changed). The item focus is cleared (focusedIndex becomes -1). Protected so a subclass can wire its choose-all row's click to focus-then-activate (mirroring how item clicks call setFocusedIndex before onItemActivated) and use it in focusInitial (the choose-all row is the listbox's FIRST option).

Returns

boolean

Inherited from

LLSelectBase.focusChooseAllRow

computeTypeaheadClosedStartIndex()

protected computeTypeaheadClosedStartIndex(_list): number

Defined in: base.ts:2984

The option the closed-state typeahead treats as current, as an index into list, when the typed character is the keystroke that opens the popup.

• The search starts AFTER this option: the opening keystroke is always a one-character buffer, because close() and a refused open() both empty the buffer.
• Default -1: no current option, so the first match from the top wins.
• The focus focusInitial parks on open is a convenience, not a selection - it must not shift this search.
• Single mode overrides this with the chosen item's index, so a typed initial cycles past the current selection like a native <select>.
• Search internals: findTypeaheadIndex in keyboard.ts.

Parameters

Returns

number

Inherited from

LLSelectBase.computeTypeaheadClosedStartIndex

focusInitial()

protected focusInitial(): void

Defined in: multiple.ts:780

On open, focus the first chosen item (if present and enabled). Otherwise the FIRST OPTION - which is the choose-all row when rendered (A11Y.md: activedescendant points at the first chosen option, else the first option; the row is the topmost option), so keyboard users discover it immediately. Else the first enabled item. Indices are into getVisibleItems().

Returns

void

Overrides

LLSelectBase.focusInitial

State (protected)

settings

protected readonly settings: S

Defined in: base.ts:972

Resolved settings (defaults applied) - ONE bag for the whole hierarchy. Typed by the class's S param: a subclass that extends the settings passes its resolved extra fields through the constructor's subclassSettings param, and this field is S with no re-typing (see LLSelectSingle / LLSelectMultiple).

Inherited from

LLSelectBase.settings

items

protected items: T[] = []

Defined in: base.ts:983

Current item list. Defensive copy of what setItems was given.

Inherited from

LLSelectBase.items

focusedIndex

protected focusedIndex: number = -1

Defined in: base.ts:992

Position in getVisibleItems() (the rendered list, not items) of the currently keyboard-focused item, or -1 when nothing is focused (closed popup, or no items).

Inherited from

LLSelectBase.focusedIndex

changeSource

protected changeSource: LLSelectChangeSource = 'api'

Defined in: base.ts:1002

Who the change being applied right now is attributed to; the variants' onChange firing reads it. Set to 'user' by withUserChangeSource and consumed (reset to 'api') by the first onChange fired, so a nested api-driven change inside an onChange handler reports 'api'.

Inherited from

LLSelectBase.changeSource

chosenItems

protected chosenItems: readonly T[] = []

Defined in: multiple.ts:195

Currently chosen items, in insertion order.

LLSelectSingle

Defined in: single.ts:75

Single-selection select. Picking an item replaces any prior chosen item and closes the popup. Use setChosenItem(undefined) to clear the selection.

Extends

• LLSelectBase<T, GroupKey, S>

Type Parameters

Selection

getChosenItem()

getChosenItem(): T | undefined

Defined in: single.ts:115

Return the currently chosen item, or undefined if none.

Returns

T | undefined

setChosenItem()

setChosenItem(item): void

Defined in: single.ts:131

Set the chosen item programmatically.

• undefined clears the choice.
• Fires onChange only when the item actually differs from the current one (compared via compareFn).
• Accepts an item that is not (yet) in the items list, for async data flows. If a later setItems does not include it, it is dropped automatically.
• It does not check disabled state: a disabled item can be chosen programmatically. Native <select> behaves the same.

Parameters

Returns

void

Items

getItems()

getItems(): readonly T[]

Defined in: base.ts:1582

Return the current item list, in data order (as passed to setItems).

• The rendered list may differ in order and content: see getVisibleItems.
• Returns the LIVE internal array, typed read-only. Do not mutate it (TS blocks it; plain-JS callers must treat it as frozen).
• Structural mutation would silently bypass chosen-state reconciliation, re-filtering, and re-render. Replace the list via setItems instead.
• Mutating item OBJECTS + rerender() is the supported in-place path.

Returns

readonly T[]

Inherited from

LLSelectBase.getItems

setItems()

setItems(items): void

Defined in: base.ts:1670

Replace the item list.

• The input is shallow-copied; later external mutation does not affect the select.
• Items MUST be unique under compareFn (it defines item identity, and the selection is a set). Duplicates render stale selection DOM; the default compareFn warns once per page, a custom compareFn is the caller's responsibility (not scanned, to keep large lists cheap).
• If the popup is open, it re-renders now. While closed, the DOM is built lazily on the next open().
• Both shipped variants re-render the trigger content from onItemsChanged (the multiple count total, custom content that reads items).
• LLSelectMultiple's triggerDisplay: 'tags' mode is opt-in; 'count' is the default.
• When triggerDisplay is 'tags', that content render is one chip per chosen item, unless createTriggerContentElFn replaces the content.
• Subclasses may reconcile chosen-state via onItemsChanged (e.g. single mode drops a chosen value that is no longer in the list).

Parameters

Returns

void

Inherited from

LLSelectBase.setItems

getVisibleItems()

getVisibleItems(): readonly T[]

Defined in: base.ts:3241

Return the items the popup list renders, in display order.

items                (setItems)
  |  gather          (only with grouping on; result cached until setItems)
  v
display base list
  |  filter query    (only while a query is active)
  v
visible items        (this method's return value)
  |  render
  v
DOM rows

• If no filter query is active (including while closed), it returns the full list, gathered per gatherGroups when grouping is on.
• If a filter query is active, it returns the matching subset.
• Disabled items are included. They render (grayed); only actions skip them (keyboard focus, the choose-all row's subset).
• Returns the LIVE internal array, typed read-only. Never mutate it (see getItems).
• Subclasses use it too (e.g. for selection-by-index), and may override it to add a step: LLSelectMultiple does for hideChosenRows.

Returns

readonly T[]

Inherited from

LLSelectBase.getVisibleItems

Open & close

open()

open(): void

Defined in: base.ts:1363

Open the popup. Builds item elements lazily, attaches the positioner (which auto-closes if the trigger is scrolled out of view), wires the outside-click handler, and moves keyboard focus into the item list. No-op if already open.

Returns

void

Inherited from

LLSelectBase.open

close()

close(): void

Defined in: base.ts:1447

Close the popup. Detaches positioner and outside-click listener, clears the item DOM, and resets focused-item state. No-op if already closed.

Focus return is decided automatically: when DOM focus is still inside the popup at the moment of close - the filter input (Esc on an empty filter, a single-select pick, an outside press on a non-focusable area) or a focusable control the app placed in a header / footer slot (Esc there, or close() called from its own click) - focus is returned to the trigger. Tab-away and outside clicks on focusable elements have already moved focus elsewhere, so we leave it alone.

Returns

void

Inherited from

LLSelectBase.close

toggle()

toggle(): void

Defined in: base.ts:1552

Open if closed, close if open.

Returns

void

Inherited from

LLSelectBase.toggle

isOpened()

isOpened(): boolean

Defined in: base.ts:1568

Whether the popup is currently open.

• Pairs with isDisabled() (state read via method).
• The same state is mirrored on the DOM as CSS hooks: data-state="open|closed" on the trigger, classIdMap.openClass on the root.

Returns

boolean

Inherited from

LLSelectBase.isOpened

Trigger

setPlaceholder()

setPlaceholder(placeholder): void

Defined in: base.ts:1643

Replace the trigger placeholder text at runtime. It is one of the two settings with a runtime setter (the other is setUiTranslationPack); both are copy. The rule: LLSelectBaseSettings.

• null = fall back to the pack default (uiTranslationPack.triggerPlaceholder), mirroring an unset constructor placeholder. An explicit value keeps winning over later setUiTranslationPack calls, exactly like the constructor input.
• Takes effect immediately. Visible only while nothing is chosen - the placeholder never renders otherwise (the trigger is still re-rendered, which also refreshes the hidden accessible-value mirror).

Parameters

Returns

void

Inherited from

LLSelectBase.setPlaceholder

Filtering

getFilterQuery()

getFilterQuery(): string

Defined in: base.ts:3271

Return the filter input's current query, exactly the string passed to filterFn.

• It is '' while the popup is closed, the filter is inactive, or the input is empty.
• It resets on close: each open cycle starts empty.

Returns

string

Inherited from

LLSelectBase.getFilterQuery

Disabling

setDisabled()

setDisabled(value): void

Defined in: base.ts:1706

Enable or disable the whole control. Disabled: the trigger gets aria-disabled + data-disabled (never the native disabled attribute, which would suppress the hover / focus events a tooltip needs), opening is blocked, an open popup closes, and the trigger leaves the tab order unless focusableWhenDisabled is set. Stored as state, mirroring setItems / setChosenItems (this design keeps mutable state out of settings).

Parameters

Returns

void

Inherited from

LLSelectBase.setDisabled

isDisabled()

isDisabled(): boolean

Defined in: base.ts:1717

Whether the whole control is disabled.

Returns

boolean

Inherited from

LLSelectBase.isDisabled

i18n

getUiTranslationPack()

getUiTranslationPack(): Readonly<LLSelectUiTranslationPack>

Defined in: base.ts:1595

Return the resolved UI strings: the built-in English defaults merged with the uiTranslationPack setting.

• Reuse these in your own UI instead of keeping a second translation source. For example, a tag remove button tooltip: sel.getUiTranslationPack().tagRemoveButtonAriaLabel(label).
• Returns the LIVE object. Treat it as immutable, like getItems.

Returns

Readonly<LLSelectUiTranslationPack>

Inherited from

LLSelectBase.getUiTranslationPack

setUiTranslationPack()

setUiTranslationPack(uiTranslationPack): void

Defined in: base.ts:1616

Replace the UI-translation pack at runtime, so switching language needs no re-new.

• One of the two settings with a runtime setter (the other is setPlaceholder); both are copy. The rule: LLSelectBaseSettings.
• The pack is resolved exactly like the constructor's: merged over the built-in English pack, NOT over the previously set pack.
• An explicit constructor placeholder keeps winning over the new pack's triggerPlaceholder.
• Re-renders the trigger and the open popup.
• Also re-applies the pack-owned attributes rerender() cannot reach: the filter input placeholder and its fallback aria-label.
• The clear button needs no such step: rerender() rebuilds it, and the rebuild reads the new pack - unless a createTriggerClearButtonEl override returns the previous element, which then owns the label.

Parameters

Returns

void

Inherited from

LLSelectBase.setUiTranslationPack

Lifecycle

rerender()

rerender(): void

Defined in: base.ts:1517

Rebuild the trigger and (while open) the popup list from current state.

• Use it after mutating item OBJECTS in place (e.g. users[0].name = 'X'). The library cannot detect that on its own.
• It re-derives the display order (the gatherGroups gather).
• While the filter is active, it re-runs the filter against the current item text.
• The refresh is purely visual: it does NOT fire onChange and does NOT run onItemsChanged.
• Orchestrator: composes renderTrigger + renderPopupList; touches no DOM directly.

Returns

void

Inherited from

LLSelectBase.rerender

destroy()

destroy(): void

Defined in: base.ts:1537

Tear down the instance: close the popup (which detaches every document / window listener and the positioner), unwire labelEl (click listener removed, a minted id removed), remove the library's class and inline styles from the caller's mount element, and empty it. Idempotent. The instance must not be used afterwards.

• REQUIRED before discarding an instance that might be OPEN (framework wrappers: call this on unmount) - skipping it there leaks the outside-click / focusout / scroll / resize listeners.
• Discarding a CLOSED instance without destroy() leaks nothing; it only leaves the root class and overflow-anchor style on the mount.

Returns

void

Inherited from

LLSelectBase.destroy

Constructor

new LLSelectSingle<T, GroupKey, S>(targetEl, settings?): LLSelectSingle<T, GroupKey, S>

Defined in: single.ts:92

Build the control inside targetEl.

• Settings are resolved once here; missing fields get defaults.
• They are frozen afterwards, except placeholder and uiTranslationPack, which have runtime setters; the rule is at LLSelectBaseSettings.
• This plain form infers T from a typed callback in settings whose signature contains T (itemToStringFn: (u: User) => ...). With no such callback, pass T explicitly: new LLSelectSingle<string>(...).

Parameters

Returns

LLSelectSingle<T, GroupKey, S>

Overrides

LLSelectBase.constructor

Constructor

new LLSelectSingle<T, GroupKey, S>(targetEl, settings?, subclassSettings?): LLSelectSingle<T, GroupKey, S>

Defined in: single.ts:98

Subclass form. subclassSettings is the typed pass-through for subclasses that extend the settings bag further; see LLSelectBase's S param.

Parameters

Returns

LLSelectSingle<T, GroupKey, S>

Overrides

LLSelectBase<T, GroupKey, S>.constructor

DOM elements

rootEl

readonly rootEl: HTMLElement

Defined in: base.ts:875

The caller-passed mount element, now decorated as the select's root. Library does not replace this node, so the caller's original reference, id, and data-* attributes stay valid.

Inherited from

LLSelectBase.rootEl

triggerEl

readonly triggerEl: HTMLElement

Defined in: base.ts:885

The interactive trigger element. Receives focus, click, and keydown events; carries aria-expanded, aria-controls, and data-state="open|closed". Its role depends on the filter mode: combobox while the filter is inactive (it then also hosts aria-activedescendant) and button while a filterable popup is open (the filter input hosts aria-activedescendant). See docs/llm/A11Y.md.

Inherited from

LLSelectBase.triggerEl

triggerContentEl

readonly triggerContentEl: HTMLElement

Defined in: base.ts:892

Inner span inside the trigger where text/tags are written. Subclasses' renderTriggerContent writes here so the sibling arrow slot is preserved across re-renders.

Inherited from

LLSelectBase.triggerContentEl

popupEl

readonly popupEl: HTMLElement

Defined in: base.ts:909

The outer popup wrapper. Has no ARIA role itself - it just hosts the popup chrome (future: filter input, toggle-all control) and the inner popupListEl. Hidden via the hidden attribute when closed; positioned via inline styles by the positioner when open.

Inherited from

LLSelectBase.popupEl

popupListEl

readonly popupListEl: HTMLElement

Defined in: base.ts:917

The inner element with role="listbox", holding the item children. Sits inside popupEl so siblings (filter input, toggle-all) can live above it without violating ARIA's "listbox children must be options" rule. The trigger's aria-controls points to this element.

Inherited from

LLSelectBase.popupListEl

popupHeaderEl

readonly popupHeaderEl: HTMLElement | null

Defined in: base.ts:925

The pinned header container between the filter input and the listbox, or null when no header content was built. No ARIA role; outside the scroll area. Built once in the constructor (createPopupHeaderEl) and kept until destroy(); the library never rebuilds or moves it.

Inherited from

LLSelectBase.popupHeaderEl

popupFooterEl

readonly popupFooterEl: HTMLElement | null

Defined in: base.ts:932

The pinned footer container at the bottom of the popup, after the no-results message, or null when no footer content was built. Same lifecycle as popupHeaderEl.

Inherited from

LLSelectBase.popupFooterEl

popupListPinnedLeadingRowsEl

readonly popupListPinnedLeadingRowsEl: HTMLElement | null

Defined in: base.ts:950

The wrapper around the pinned leading rows, or null.

• Built once in the constructor when popupListLeadingRowsPinned is true; null otherwise.
• A div with role="presentation" and class popupListPinnedLeadingRowsClass; the library sets position: sticky and top: 0 on it inline.
• In the listbox only while the leading rows exist. The library moves it in and out on every list render. Its classes are yours to change after new.
• data-edge-to-items is set on every list render: "true" when that render lists items, "false" when it lists none; absent before the first render.
• It is a CSS hook for the themes: they draw the block's edge line only when it is true, so two blocks that touch draw no line between them.

Inherited from

LLSelectBase.popupListPinnedLeadingRowsEl

popupListPinnedTrailingRowsEl

readonly popupListPinnedTrailingRowsEl: HTMLElement | null

Defined in: base.ts:957

The wrapper around the pinned trailing rows, or null.

• Same contract as popupListPinnedLeadingRowsEl, for popupListTrailingRowsPinned, with bottom: 0.

Inherited from

LLSelectBase.popupListPinnedTrailingRowsEl

classIdMap

readonly classIdMap: LLSelectClassIdMap

Defined in: base.ts:962

Resolved class names and ids for this instance.

Inherited from

LLSelectBase.classIdMap

triggerValueEl

protected readonly triggerValueEl: HTMLElement

Defined in: base.ts:901

Hidden root-level span (sibling of the trigger) mirroring the current value as plain text. Kept in sync by commitTriggerContentToDom; referenced by the filterable-mode aria-labelledby chain (see classIdMap.triggerValueId). Outside the trigger so triggerEl.textContent stays exactly the visible content.

Inherited from

LLSelectBase.triggerValueEl

Subclassing: reactions

onOpened()

protected onOpened(): void

Defined in: base.ts:1753

Subclass hook: called once after the popup finishes opening. Default no-op. The onOpen setting fires alongside this (both run) - hook for subclass logic, setting for consumer notification.

Returns

void

Inherited from

LLSelectBase.onOpened

onClosed()

protected onClosed(): void

Defined in: base.ts:1758

Subclass hook: called once after the popup finishes closing. Pairs with the onClose setting (both run).

Returns

void

Inherited from

LLSelectBase.onClosed

onChosenChanged()

protected onChosenChanged(): void

Defined in: base.ts:1765

Subclass hook: called after the chosen state actually changed, right before the variant's onChange setting fires (hook first, both run - same pairing as onOpened / onClosed). Default no-op.

Returns

void

Inherited from

LLSelectBase.onChosenChanged

onPopupListActionRowActivated()

protected onPopupListActionRowActivated(row): void

Defined in: base.ts:2522

Subclass hook: an action row was activated.

• The library calls it on Enter, on Space while the filter is inactive, and on click, after the disabled re-check, as a user change. You never call it. row comes from the library: the activated entry.
• Default calls the entry's onActivate. The library changes nothing else: choosing and closing are the entry's job.
• Override to react before or after: do your work, then call super.onPopupListActionRowActivated(row). Without that call the entry's onActivate never runs.

Parameters

Returns

void

Inherited from

LLSelectBase.onPopupListActionRowActivated

withUserChangeSource()

protected withUserChangeSource<R>(fn): R

Defined in: base.ts:2582

Run fn with chosen-state changes attributed to the user. The library wraps exactly its pointer / keyboard entry points with it - option activation, the tag remove button, the clear button, the choose-all row; everything else reports 'api'.

Type Parameters

Parameters

Returns

R

Inherited from

LLSelectBase.withUserChangeSource

onChooseAllRowActivated()

protected onChooseAllRowActivated(): void

Defined in: base.ts:2597

Subclass hook: the choose-all row was activated - Enter while it is focused (subclasses also wire their row's click handler to this). Default no-op.

Returns

void

Inherited from

LLSelectBase.onChooseAllRowActivated

onItemActivated()

protected onItemActivated(item): void

Defined in: single.ts:186

Pick this item as the chosen item and close the popup.

Parameters

Returns

void

Overrides

LLSelectBase.onItemActivated

onItemsChanged()

protected onItemsChanged(): void

Defined in: single.ts:247

Re-match the chosen item against the new list after setItems.

• If the list no longer holds it (by compareFn), it is dropped and onChange fires.
• If the list holds a compareFn-equal but DIFFERENT object (track by style reload: same key, fresh fields), the stored reference is swapped to the list's object. The logical value did not change, so onChange does not fire.
• The trigger content re-renders after every setItems, because a custom createTriggerContentElFn receives items.
• The arrow re-renders only when the chosen item is dropped, because that runs the whole trigger.

Returns

void

Overrides

LLSelectBase.onItemsChanged

Subclassing: rendering

renderTrigger()

protected renderTrigger(): void

Defined in: base.ts:1810

Orchestrator: composes the clear-button rebuild + renderTriggerContent + renderTriggerArrow to (re)build the whole trigger from state; touches no DOM directly. Subclasses normally override renderTriggerContent, not this.

• Runs on every change of the chosen value, the placeholder or the pack.
• rerender() runs it too.
• While clearable is on, the first run builds the clear button and every later run swaps it for whatever createTriggerClearButtonEl returns: a fresh button from the base implementation, like the arrow. An override may return the previous element; it is then kept in place.
• If the button is rebuilt and the old one held focus - on it or inside its icon - the rebuilt BUTTON gets it.
• If the builder returned the same element, nothing was rebuilt, and focus goes back to the node that held it, if that node is still inside the button and can take focus; otherwise focus stays on the button.
• setItems runs renderTriggerContent alone, because only the content reads the list (the multiple count total, a custom createTriggerContentElFn's items).
• A setItems that drops the chosen entry runs the whole trigger.
• Runs once from the LLSelectSingle / LLSelectMultiple constructor, right after super().
• On that first run a FURTHER subclass's own fields are still undefined: JS runs a subclass's field initializers only after its super constructor returns (virtual-call-in-constructor). An override of a trigger method (renderTriggerContent, or a create*El it calls) that reads such a field sees undefined there.
• The recipe: put construction-time configuration in the typed subclassSettings constructor param. this.settings is complete before any construction code runs.
• For genuine instance state, tolerate defaults during construction, or call rerender() at the end of your own constructor.
• The popup-list methods do NOT run here; they wait for open(). See DESIGN.md "Customization model".

Returns

void

Inherited from

LLSelectBase.renderTrigger

commitTriggerContentToDom()

protected commitTriggerContentToDom(content, plainTextValue?): void

Defined in: base.ts:1833

Write the trigger's content slot (triggerContentEl), replacing whatever was there; the sibling arrow slot is untouched. The single DOM-writing primitive behind every renderTriggerContent path.

• string -> set as textContent (plain text, NOT parsed as HTML). Used for the default placeholder / itemToString text / count summary.
• HTMLElement -> inserted as-is via replaceChildren; caller owns the node. Used for whatever the createTriggerContentElFn setting returned.
• Also mirrors the value into the hidden triggerValueEl (the accessible name source): the string itself, else plainTextValue, else the element's textContent. Pass plainTextValue whenever the element contains labelled controls (tag remove buttons) or icon-only content - the mirror is what AT announces as the field's value. Called by renderTriggerContent - the base default and the LLSelectSingle / LLSelectMultiple overrides.

Parameters

Returns

void

Inherited from

LLSelectBase.commitTriggerContentToDom

syncEmptyStateToDom()

protected syncEmptyStateToDom(): void

Defined in: base.ts:1850

Mirror the empty/filled state onto the trigger's data-empty attribute ("true" when isEmpty(), else "false"). A CSS / AT styling hook, independent of the rendered content. Called by the subclass renderTriggerContent overrides.

Returns

void

Inherited from

LLSelectBase.syncEmptyStateToDom

createTriggerArrowContentEl()

protected createTriggerArrowContentEl(state): HTMLElement | SVGElement | null

Defined in: base.ts:1896

Trigger arrow element for the given open state.

• Default reads createTriggerArrowContentElFn; null (setting unset, or returned for a state) = no arrow for that state.
• Override only when extending; for one-off arrows pass the setting. Mirrors createTriggerClearButtonEl / createItemContentEl.

Parameters

Returns

HTMLElement | SVGElement | null

Inherited from

LLSelectBase.createTriggerArrowContentEl

renderPopupList()

protected renderPopupList(): void

Defined in: base.ts:1929

Orchestrator: composes createItemEl (build) + computePopupSegments + commitPopupSegmentsToDom (write) to rebuild the popup list from getVisibleItems(); touches no DOM directly. Called by open() and by setItems() while open. Also clamps focusedIndex if the list shrank and re-applies focus visuals.

• Extend it by wrapping: override, do your work before or after, then call super.renderPopupList(). The ui-select bridge frees its row scopes this way. Or override one of the methods it calls through this: createItemEl, createPopupListChooseAllRowEl, createPopupListLeadingActionRowEl / createPopupListTrailingActionRowEl, itemToGroupKey, getVisibleItems.
• Its other internals stay private on purpose. They re-establish the itemEls[i] <-> getVisibleItems()[i] alignment as one unit, so no subclass can leave keyboard nav or aria-activedescendant half-synced.

Returns

void

Inherited from

LLSelectBase.renderPopupList

createGroupEl()

protected createGroupEl(key, index, items, itemEls): HTMLElement

Defined in: base.ts:2064

Build the whole DOM element for one group container.

• The library calls it, once per group of the current render, on every list render. You never call it yourself.
• All four params come from the library. Forward them to super unchanged.
• index is the group's position among this render's groups, counted from 0. It only mints the group id. It is not an identity: it changes whenever the visible list changes.
• To change only the label's content, do not override this. Pass the createGroupLabelContentElFn setting instead.
• To change the element itself, override it, call super.createGroupEl(...), and edit the returned element. Keep the role and aria-label the base set.
• Internals: the base sets the id, role="group" named by groupKeyToString (aria-label), an aria-hidden visible label element filled from createGroupLabelContentEl (else the plain label text), then the group's item elements; aria-disabled + data-disabled when the group is disabled.

Parameters

Returns

HTMLElement

Inherited from

LLSelectBase.createGroupEl

createGroupLabelContentEl()

protected createGroupLabelContentEl(key, itemsInGroup): HTMLElement | null

Defined in: base.ts:2098

Group label -> its visible content element (icon / count badge / rich markup). Mirrors createItemContentEl.

• Default reads createGroupLabelContentElFn, else null so createGroupEl uses plain text from groupKeyToString.
• The group's accessible name stays groupKeyToString (container aria-label); this fills only the visible, aria-hidden label content.
• Override only when extending; for one-off rich labels pass the setting.

Parameters

Returns

HTMLElement | null

Inherited from

LLSelectBase.createGroupLabelContentEl

replacePopupListItemElInDom()

protected replacePopupListItemElInDom(item): void

Defined in: base.ts:2112

Re-render a single item's element in place instead of rebuilding the whole popup list. The DOM work is O(1) regardless of list size, so flipping one selection in a 10k-item list does not recreate 10k nodes (the lookup to find the item is O(n), but that is a cheap comparison loop next to DOM mutation). No-op if the popup is closed or the item is not in the current list. Used by multi-select toggle.

Parameters

Returns

void

Inherited from

LLSelectBase.replacePopupListItemElInDom

createItemContentEl()

protected createItemContentEl(item): HTMLElement | null

Defined in: base.ts:2222

Item -> the visible content of its list row (icon + text etc.).

• Default reads createItemContentElFn, else null so createItemEl uses the plain-text default from itemToString.
• Override only when extending; for one-off rich content pass the setting.

Parameters

Returns

HTMLElement | null

Inherited from

LLSelectBase.createItemContentEl

createPopupListLeadingActionRowEl()

protected createPopupListLeadingActionRowEl(row, index): HTMLElement

Defined in: base.ts:2427

Build the whole DOM element for one leading action row (above the items).

• The library calls it, once per entry of popupListLeadingActionRows, on every list render and after every chosen change. You never call it.
• Both params come from the library. Forward them to super unchanged. row is the entry; index is its position in that array, counted from 0, used to mint the id. It is not an identity.
• To change only what the row shows, do not override this: give the entry a createContentElFn.
• To change the element itself, override it, call super.createPopupListLeadingActionRowEl(row, index), and edit the returned element. Keep the id and role; put no focusable control inside.
• Internals: a div with role="option", the id <listbox id>-action-row-leading<index>, itemClass plus popupListActionRowClass, the visible content from createPopupListActionRowContentEl (else textContent from textFn), aria-label = textFn() when the content is custom, and either aria-disabled plus the disabled class (isPopupListActionRowDisabled) or a click handler that focuses the row, then runs onPopupListActionRowActivated. No aria-selected: a command has no selected state.

Parameters

Returns

HTMLElement

Inherited from

LLSelectBase.createPopupListLeadingActionRowEl

createPopupListTrailingActionRowEl()

protected createPopupListTrailingActionRowEl(row, index): HTMLElement

Defined in: base.ts:2450

Build the whole DOM element for one trailing action row (below the items).

• The library calls it, once per entry of popupListTrailingActionRows, on every list render and after every chosen change. You never call it.
• Both params come from the library. Forward them to super unchanged. row is the entry; index is its position in that array, counted from 0, used to mint the id. It is not an identity.
• To change only what the row shows, do not override this: give the entry a createContentElFn.
• To change the element itself, override it, call super.createPopupListTrailingActionRowEl(row, index), and edit the returned element. Keep the id and role; put no focusable control inside.
• Internals: identical to createPopupListLeadingActionRowEl except the id, <listbox id>-action-row-trailing<index>.

Parameters

Returns

HTMLElement

Inherited from

LLSelectBase.createPopupListTrailingActionRowEl

createPopupListActionRowContentEl()

protected createPopupListActionRowContentEl(row): HTMLElement | null

Defined in: base.ts:2493

An action row's visible content element.

• The library calls it from the row builders, once per row render. You never call it. row comes from the library.
• Default reads the entry's createContentElFn; null (unset, or returned) = plain text from textFn.
• Override only when extending; for one-off content give the entry a createContentElFn.

Parameters

Returns

HTMLElement | null

Inherited from

LLSelectBase.createPopupListActionRowContentEl

replacePopupListActionRowElsInDom()

protected replacePopupListActionRowElsInDom(): void

Defined in: base.ts:2538

Rebuild every rendered action row in place, so textFn / disabledFn reflect the current state; the row holding the active option keeps it.

• The library calls it after every chosen change, right after onChange fired (a row's text may read what the handler wrote). Subclasses may call it after a state change of their own.
• No-op while closed, or when both row arrays are empty - instances without rows pay nothing.
• O(rows) DOM work; the item rows are untouched.

Returns

void

Inherited from

LLSelectBase.replacePopupListActionRowElsInDom

createPopupListChooseAllRowEl()

protected createPopupListChooseAllRowEl(): HTMLElement | null

Defined in: base.ts:2573

Optional non-item role="option" row placed first, at the TOP of the listbox: inside the arrow-key ring (ArrowUp from the first item reaches it, Home lands on it, up-actions clamp there) but never inside itemEls, so the itemEls[i] <-> getVisibleItems()[i] alignment is untouched. Rebuilt on every renderPopupList. Base default: null = no choose-all row. LLSelectMultiple builds its choose-all row here (chooseAllRow setting).

Returns

HTMLElement | null

Inherited from

LLSelectBase.createPopupListChooseAllRowEl

replaceChooseAllRowElInDom()

protected replaceChooseAllRowElInDom(): void

Defined in: base.ts:2652

Rebuild the choose-all row in place (tri-state / text refresh) without touching the item elements - O(1) DOM work, mirroring replacePopupListItemElInDom. Falls back to a full renderPopupList when the row becomes inapplicable (builder returns null). No-op while closed or when no choose-all row is rendered.

Returns

void

Inherited from

LLSelectBase.replaceChooseAllRowElInDom

createTriggerClearButtonEl()

protected createTriggerClearButtonEl(): HTMLElement

Defined in: base.ts:3047

Build the clear (x) button for the clearable trigger slot.

• The library owns the button, its click (stops propagation so it never toggles the popup, then clearSelection; a no-op while the control is disabled) and its aria-label (text from uiTranslationPack.triggerClearButtonAriaLabel).
• createTriggerClearButtonContentElFn optionally fills the icon; else the theme's CSS glyph draws it.
• The theme hides the button via data-empty while nothing is chosen.
• It runs on every trigger render (renderTrigger).
• The first run builds the button.
• For LLSelectSingle / LLSelectMultiple and their subclasses, that first run is the variant constructor's render, right after super(), so it happens before a FURTHER subclass's field initializers.
• A direct LLSelectBase subclass gets the button on its first trigger render (its own renderTrigger() call, or rerender() / setPlaceholder); until then the trigger is unrendered and there is no button.
• Every later run (a value change, setPlaceholder, setUiTranslationPack, rerender()) swaps the button in place, unless this method returns the previous element - then it stays in place.
• The base implementation returns a fresh element each run, so, like the arrow, nothing put on it from outside survives a render; customize it here.
• An override that returns the same element every time owns everything the rebuild would otherwise refresh on it, including its aria-label after setUiTranslationPack.
• An override that reads subclass fields calls rerender() at the end of its constructor, like every other trigger method.

Returns

HTMLElement

Inherited from

LLSelectBase.createTriggerClearButtonEl

createTriggerClearButtonContentEl()

protected createTriggerClearButtonContentEl(): HTMLElement | SVGElement | null

Defined in: base.ts:3174

Clear button's visible content (its x icon).

• Default reads createTriggerClearButtonContentElFn; null (setting unset, or returned) = no icon - the theme's CSS glyph draws the x.
• Override only when extending; for one-off icons pass the setting.

Returns

HTMLElement | SVGElement | null

Inherited from

LLSelectBase.createTriggerClearButtonContentEl

createPopupListNoResultsContentEl()

protected createPopupListNoResultsContentEl(query): HTMLElement | null

Defined in: base.ts:3356

The no-results message's visible content (rich empty-state).

• Default reads createPopupListNoResultsContentElFn; null (setting unset, or returned) = plain text from uiTranslationPack.popupListNoResults.
• Override only when extending; for one-off content pass the setting.

Parameters

Returns

HTMLElement | null

Inherited from

LLSelectBase.createPopupListNoResultsContentEl

createPopupHeaderEl()

protected createPopupHeaderEl(): HTMLElement | null

Defined in: base.ts:3376

Build the pinned header container between the filter input and the listbox.

• The library calls it once, inside the constructor. You never call it.
• It takes no params. The default asks createPopupHeaderContentEl for content; null content = no container, and popupHeaderEl stays null.
• To supply content without subclassing, pass createPopupHeaderContentElFn.
• To change the container itself, override it: call super.createPopupHeaderEl() and edit the returned element, or return your own div. Returning non-null builds the slot even without the setting. Keep it role-free: it is not part of the listbox.
• Internals: the base builds a div with classIdMap.popupHeaderClass and inline flex: none (the popup is a flex column and only the listbox may flex), then appends the content.

Returns

HTMLElement | null

Inherited from

LLSelectBase.createPopupHeaderEl

createPopupHeaderContentEl()

protected createPopupHeaderContentEl(): HTMLElement | null

Defined in: base.ts:3390

The pinned header's content element.

• The library calls it once, from createPopupHeaderEl, inside the constructor. You never call it.
• Default calls createPopupHeaderContentElFn with a LLSelectConstructionContext; null (setting unset, or returned) = no header at all.
• Override only when extending; for one-off content pass the setting.

Returns

HTMLElement | null

Inherited from

LLSelectBase.createPopupHeaderContentEl

createPopupFooterEl()

protected createPopupFooterEl(): HTMLElement | null

Defined in: base.ts:3410

Build the pinned footer container at the bottom of the popup.

• The library calls it once, inside the constructor. You never call it.
• It takes no params. The default asks createPopupFooterContentEl for content; null content = no container, and popupFooterEl stays null.
• To supply content without subclassing, pass createPopupFooterContentElFn.
• To change the container itself, override it: call super.createPopupFooterEl() and edit the returned element, or return your own div. Returning non-null builds the slot even without the setting. Keep it role-free: it is not part of the listbox.
• Internals: the base builds a div with classIdMap.popupFooterClass and inline flex: none (only the listbox may flex), then appends the content.

Returns

HTMLElement | null

Inherited from

LLSelectBase.createPopupFooterEl

createPopupFooterContentEl()

protected createPopupFooterContentEl(): HTMLElement | null

Defined in: base.ts:3424

The pinned footer's content element.

• The library calls it once, from createPopupFooterEl, inside the constructor. You never call it.
• Default calls createPopupFooterContentElFn with a LLSelectConstructionContext; null (setting unset, or returned) = no footer at all.
• Override only when extending; for one-off content pass the setting.

Returns

HTMLElement | null

Inherited from

LLSelectBase.createPopupFooterContentEl

renderTriggerContent()

protected renderTriggerContent(): void

Defined in: single.ts:152

Orchestrator: composes syncEmptyStateToDom + commitTriggerContentToDom to (re)build the trigger from state; touches no DOM directly.

• createTriggerContentElFn is tried first; if it returns null or is unset, the default applies.
• The default is the chosen item's string, or the placeholder when nothing is chosen.

Returns

void

Overrides

LLSelectBase.renderTriggerContent

createItemEl()

protected createItemEl(item, index): HTMLElement

Defined in: single.ts:176

Mark the chosen option aria-selected="true", the rest "false" (APG select-only).

Parameters

Returns

HTMLElement

Overrides

LLSelectBase.createItemEl

Subclassing: semantics

itemToString()

protected itemToString(item): string

Defined in: base.ts:2210

Map an item to its display string. The library calls this everywhere it needs an item's text: list rows, the single trigger text, default filter.

• Default reads the itemToStringFn setting, else String(item).
• Configure via itemToStringFn (no subclass needed).
• Override only when extending (a new select type); your override replaces the default. For HTML content, subclass createItemEl.

Parameters

Returns

string

Inherited from

LLSelectBase.itemToString

isItemEffectivelyDisabled()

protected isItemEffectivelyDisabled(item): boolean

Defined in: base.ts:2236

Whether item is effectively disabled - by itemDisabledFn, or because its group is disabled (groupDisabledFn). Group-disabled layers on top, so every item-disabled behavior (no selection, keyboard skip, aria) covers grouped items with no extra code. False when neither applies. The whole-control disabled state (isDisabled()) is a separate layer, not part of this answer.

Parameters

Returns

boolean

Inherited from

LLSelectBase.isItemEffectivelyDisabled

itemToGroupKey()

protected itemToGroupKey(item): GroupKey | null

Defined in: base.ts:2255

Map an item to its group key, or null when it belongs to no group. The authoritative method: rendering, the gatherGroups gather, and the disabled layer all resolve keys through this method, so an override drives them all - returning keys turns grouping on even with the setting unset (all-null keys = flat list). An override reading external state must call rerender() after that state changes (same contract as mutating item objects).

• Default reads itemToGroupKeyFn, else null (grouping off).
• Override only when extending; configure via the setting.

Parameters

Returns

GroupKey | null

Inherited from

LLSelectBase.itemToGroupKey

groupKeyToString()

protected groupKeyToString(key): string

Defined in: base.ts:2265

Map a group key to its label display text.

• Default reads groupKeyToStringFn, else String(key).

Parameters

Returns

string

Inherited from

LLSelectBase.groupKeyToString

isGroupDisabled()

protected isGroupDisabled(key): boolean

Defined in: base.ts:2274

Whether the whole group key is disabled per groupDisabledFn (false when unset).

Parameters

Returns

boolean

Inherited from

LLSelectBase.isGroupDisabled

isPopupListActionRowDisabled()

protected isPopupListActionRowDisabled(row): boolean

Defined in: base.ts:2505

Whether an action row is disabled right now.

• The library calls it from the row builders (once per row render) and again at activation. You never call it. row comes from the library.
• Default reads the entry's disabledFn; null / omitted = never disabled.

Parameters

Returns

boolean

Inherited from

LLSelectBase.isPopupListActionRowDisabled

matchesQuery()

protected matchesQuery(item, query): boolean

Defined in: base.ts:3283

Per-item match predicate for the filter input.

• Default reads filterFn; else case-insensitive substring on itemToString.
• Override only when extending (subclass-wide custom matching); for a one-off match rule pass the setting.

Parameters

Returns

boolean

Inherited from

LLSelectBase.matchesQuery

isEmpty()

protected isEmpty(): boolean

Defined in: single.ts:168

No selection iff chosenItem is unset. Drives the trigger's data-empty.

Returns

boolean

Overrides

LLSelectBase.isEmpty

clearSelection()

protected clearSelection(): void

Defined in: single.ts:195

Clear button empties the single selection to undefined.

Returns

void

Overrides

LLSelectBase.clearSelection

Subclassing: focus

findNextEnabledIndex()

protected findNextEnabledIndex(start, step, list): number

Defined in: base.ts:2285

First enabled index scanning from start (inclusive) by step (+1 / -1). Returns -1 if no enabled item lies in that direction. Used to skip disabled items during keyboard nav and initial focus.

Parameters

Returns

number

Inherited from

LLSelectBase.findNextEnabledIndex

setFocusedIndex()

protected setFocusedIndex(index): void

Defined in: base.ts:2617

Move keyboard focus to the item at index. The value is clamped to [-1, items.length-1]; pass -1 to clear focus. Updates the focused class, aria-activedescendant, and scrolls the item into view. No-op if the clamped value equals the current focused index.

Parameters

Returns

void

Inherited from

LLSelectBase.setFocusedIndex

focusChooseAllRow()

protected focusChooseAllRow(): boolean

Defined in: base.ts:2635

Move keyboard focus onto the choose-all row. Returns whether the row is now focused (false = none is rendered, nothing changed). The item focus is cleared (focusedIndex becomes -1). Protected so a subclass can wire its choose-all row's click to focus-then-activate (mirroring how item clicks call setFocusedIndex before onItemActivated) and use it in focusInitial (the choose-all row is the listbox's FIRST option).

Returns

boolean

Inherited from

LLSelectBase.focusChooseAllRow

focusInitial()

protected focusInitial(): void

Defined in: single.ts:204

On open, focus the chosen item (if present and enabled), else the first enabled item. Indices are into getVisibleItems() (the rendered list).

Returns

void

Overrides

LLSelectBase.focusInitial

computeTypeaheadClosedStartIndex()

protected computeTypeaheadClosedStartIndex(list): number

Defined in: single.ts:226

Closed-state typeahead searches relative to the CHOSEN item, like a native <select>: typing its initial cycles to the next match.

• Returns -1 when nothing is chosen, or the chosen item left the list; the search then starts from the top.

Parameters

Returns

number

Overrides

LLSelectBase.computeTypeaheadClosedStartIndex

State (protected)

settings

protected readonly settings: S

Defined in: base.ts:972

Resolved settings (defaults applied) - ONE bag for the whole hierarchy. Typed by the class's S param: a subclass that extends the settings passes its resolved extra fields through the constructor's subclassSettings param, and this field is S with no re-typing (see LLSelectSingle / LLSelectMultiple).

Inherited from

LLSelectBase.settings

items

protected items: T[] = []

Defined in: base.ts:983

Current item list. Defensive copy of what setItems was given.

Inherited from

LLSelectBase.items

focusedIndex

protected focusedIndex: number = -1

Defined in: base.ts:992

Position in getVisibleItems() (the rendered list, not items) of the currently keyboard-focused item, or -1 when nothing is focused (closed popup, or no items).