Combobox core
framework-independentThe state machine used by every adapter. It owns selection, filtering, validation, keyboard navigation, popup lifecycle, anchoring, and focus management. It does not render anything and does not import a framework.
Install
pnpm add @pdanpdan/headless-combobox-core
Usage
Create the store, push props with setProps, and call mount() when the DOM is available. The snapshot contains state, actions, ARIA prop bags, and ref setters. Call destroy() when the host unmounts.
import { createCombobox } from '@pdanpdan/headless-combobox-core';
const combobox = createCombobox({
props: {
modelValue: null,
options: [ 'Vue', 'React', 'Svelte', 'Solid', 'Angular' ],
},
onChange: (value) => {
console.log('selection', value);
},
});
combobox.mount();
const state = combobox.getSnapshot();
state.open();
state.select('Vue');
state.close();
combobox.destroy();
Keyboard
| Name | Type | Description |
|---|---|---|
| Enter / Space / ArrowDown / ArrowUp | popup closed | Open the dropdown. |
| Backspace / Delete | popup closed, or open without a filter input | Remove the last (or only) selected option. Text inputs keep their native editing behavior. |
| ArrowDown / ArrowUp | popup open | Move the highlight; wraps around and skips disabled options. |
| PageDown / PageUp | popup open | Move the highlight a full page (visible options), clamped at the ends. |
| Home / End | popup open | Jump to the first or last selectable option (native caret behavior in inputs). |
| Enter | popup open | Select the highlighted option. |
| Space | popup open | Does nothing on the trigger; options and text entries keep their native behavior. |
| Tab / Shift+Tab | popup open | Skip the options list to the next focusable element; closes when focus leaves the widget (selectOnTab selects first). |
| Escape | popup open | Close the popup and return focus to the trigger. |
Clicking the trigger toggles the popup. Hovering or focusing an option highlights it, clicking selects it, and clicking outside the container closes the popup. Escape works from anywhere inside the widget.
Factory options
| Name | Type | Description |
|---|---|---|
| props | HeadlessComboboxProps<O, V, Q> | Initial props: options, modelValue, selection mode, filtering, validation, and behavior flags. |
| onChange | (value: V | V[] | null) => void | Called for every selection change. |
| runtime | ComboboxRuntimeOverrides | Host hooks for nextTick, unwrap, createId, and document lookup. |
Props
These fields go inside the props object. Reactive adapters call setProps whenever their inputs change.
| Name | Type | Default | Description |
|---|---|---|---|
| modelValue | V | V[] | null | undefined | Selected value(s). Omit it to let the store keep the selection internally. |
| options | O[] | n/a | List of options. |
| multiple | boolean | false | Enable multiple selection. |
| minLength | number | n/a | Multiple: minimum number of selected options (validation). |
| maxLength | number | n/a | Multiple: maximum selected. Blocks adding beyond it. |
| required | boolean | false | Require a selection (single: a value; multiple: at least one). |
| disabled | boolean | false | Disable the control: not focusable, cannot open or change. |
| readonly | boolean | false | Read-only: focusable, shows the value, but cannot open or change. |
| closeOnSelect | boolean | null | !multiple | Close the dropdown after selecting. |
| closeOnClickOutside | boolean | true | Close when clicking outside the widget boundary. |
| clickOutsideFilter | (target: EventTarget | null) => boolean | n/a | Return false to keep the dropdown open for an outside target. |
| selectOnTab | boolean | false | On Tab, when focus leaves the widget: select the highlighted option and close. |
| optionValue | (option: O) => V | option itself | Maps an option to the value stored in the model. |
| optionLabel | (option: O) => string | String(option) | Maps an option to a string for filtering and rendering. |
| optionFilter | (option: O, query: Q) => boolean | substring | Custom filter function. Q defaults to string. |
| id | string | generated | Base id for accessibility attributes. |
| alignSelected | boolean | false | Align the dropdown so the selected option covers the trigger. |
| errorMessages | Partial<Record<HeadlessComboboxErrorCode, string>> | n/a | Override default validation messages. |
Snapshot
State
Values for the current selection and popup.
| Name | Type | Description |
|---|---|---|
| isOpen | boolean | Whether the dropdown is open. |
| multiple | boolean | Whether multiple selection is enabled. |
| disabled | boolean | Whether the control is disabled. |
| readonly | boolean | Whether the control is read-only. |
| searchQuery | Q | undefined | Current search query. Q defaults to string. |
| filteredOptions | T[] | Options after applying the filter. |
| highlightedIndex | number | Index of the highlighted option (-1 when none). |
| alignmentOffset | number | Pixel offset used for alignment. |
| cssAnchorName | string | Unique CSS anchor-name for popover positioning. |
| popupStyle | HeadlessComboboxPopupStyle | Default popup positioning style. Spread or merge it onto the dropdown. |
| selectedCount | number | Number of selected options. |
| selectedList | V[] | Selected values (single mode: a single-element array). |
| canSelectMore | boolean | False when at maxLength (multiple). |
| isSelected | (option: T) => boolean | Whether an option is selected. |
| valid | boolean | Whether the current selection passes validation. |
| errors | HeadlessComboboxErrorCode[] | Active validation errors ('required' | 'minlength' | 'maxlength'). |
| validationMessage | string | Human-readable message for the first error. |
ARIA prop bags
Attributes and handlers for your markup.
| Name | Type | Description |
|---|---|---|
| triggerProps | HeadlessComboboxTriggerProps | role=combobox, aria-expanded, aria-activedescendant, toggle and keydown handlers. |
| inputProps | HeadlessComboboxInputProps | Search input attributes, aria-activedescendant, and keydown handling. |
| comboboxInputProps | HeadlessComboboxComboboxInputProps | Typeahead input attributes, open and focus handlers. |
| listboxProps | HeadlessComboboxListboxProps | role=listbox and aria-multiselectable. |
| getOptionProps | (option, index) => HeadlessComboboxOptionProps | role=option, aria-selected, aria-disabled, and select and highlight handlers. |
Actions
Methods that drive the state machine.
| Name | Type | Description |
|---|---|---|
| toggle | () => void | Toggle the dropdown open or closed. |
| open | () => void | Open the dropdown. |
| close | (returnFocus?: boolean) => void | Close the dropdown. |
| select | (option: T) => void | Select (single) or toggle (multiple) an option. |
| clear | () => void | Clear the selection (null or []). |
| setSearchQuery | (value: Q | undefined) => void | Update the search query. |
| setHighlightedIndex | (index: number) => void | Set the highlighted option. Wire it to hover to match keyboard behavior. |
| focusInput | () => void | Focus the filter input while the popup stays open. |
| handleKeydown | (event: KeyboardEvent) => void | Keyboard navigation handler. |
Ref setters
Attach DOM elements to the store.
| Name | Type | Description |
|---|---|---|
| setContainerRef | ref fn | The root container element. |
| setTriggerRef | ref fn | The trigger button or typeahead input. |
| setDropdownRef | ref fn | The dropdown popup element. |
| setInputRef | ref fn | The search input element. |
| setListRef | ref fn | The options list element. |
| setOptionRef | (option, el) => void | Each option element. Needed for alignSelected and scroll-into-view. |
Runtime
Adapters override these hooks so the core can wait for a framework render, unwrap proxies, and use the framework's id generator.
| Name | Type | Description |
|---|---|---|
| nextTick | () => Promise<void> | Resolve after the host has committed the DOM. Defaults to Promise.resolve(). |
| unwrap | <T>(value: T) => T | Strip framework proxies before identity comparisons. Defaults to identity. |
| createId | () => string | Stable id source for accessibility attributes. |
| getDocument | () => Document | null | Document access for listeners. Defaults to the global document when available. |