ComboBox

ComboBox combines text input, popover, and listbox behavior into a single accessible selection pattern. It supports single and multiple selection, controlled and uncontrolled state, keyboard-first interaction, and async pending states.

Anatomy

ComboBox.Root owns the open state, input value, selection logic, and filtering; the remaining parts compose freely inside it. ComboBox.Clear and ComboBox.Trigger are optional affordances that never steal focus from the input.

<script>
	import { ComboBox } from '@human-kit/ui';
</script>

<ComboBox.Root>
	<ComboBox.Input />
	<ComboBox.Clear />
	<ComboBox.Trigger />
	<ComboBox.Popover>
		<ComboBox.List>
			<ComboBox.Item id="1">Option 1</ComboBox.Item>
		</ComboBox.List>
	</ComboBox.Popover>
</ComboBox.Root>

Multiple selection with tags

Set selectionMode="multiple" and render the selected values with ComboBox.Tags, ComboBox.Tag, and ComboBox.TagRemove. The popover stays open after each selection, and Backspace in an empty input removes the last tag.

Opening modes

trigger controls when the popover opens: "focus" opens as soon as the input is focused, "input" opens once the user starts typing, and "press" opens only when ComboBox.Trigger is pressed. Switch the mode below and reopen the field to feel the difference.

Pending state

Set pending on ComboBox.Root to expose async loading state: the root gets data-pending, while the trigger and clear buttons become non-interactive. The input stays editable so the user can keep refining the query.

Usage guidelines

• Wrap all parts in ComboBox.Root.
• Use controlled props (value, inputValue, open) only when external state management is needed.
• Use pending on ComboBox.Root to expose async loading state on the root while keeping the rest of the composition under your control.
• Prefer ComboBox.Trigger in new code. ComboBox.Button remains available as a compatibility alias.
• Use ComboBox.Clear when you want a built-in clear affordance that resets both the input and selected value.
• Render ComboBox.Tags, ComboBox.Tag, and ComboBox.TagRemove in multiple mode to expose selected values.
• Choose trigger="focus", trigger="input", or trigger="press" based on your opening behavior requirements.
• Provide a stable id in SSR environments to keep ARIA ids deterministic.

Accessibility

• ComboBox.Input renders role="combobox" with aria-autocomplete="list", aria-haspopup="listbox", aria-expanded, and aria-controls pointing at the list.
• DOM focus stays in the input while arrow keys move a virtual focus through the options via aria-activedescendant.
• The list renders role="listbox"; options render role="option" with aria-selected.
• Enter selects the highlighted option, Escape closes the popover, and typing filters the list.
• Provide aria-label or aria-labelledby on ComboBox.Root or ComboBox.Input when there is no visible label.

API reference

Root

State container for the combobox. Owns open state, input value, selection logic, filtering, and keyboard interaction.

* required. Native HTML attributes of the underlying element are also accepted.

Input

Text input with role="combobox" that syncs the typed value, active descendant, and keyboard handling with the root.

* required. Native HTML attributes of the underlying element are also accepted.

Trigger

Optional button that toggles the popover without stealing focus from the input.

* required. Native HTML attributes of the underlying element are also accepted.

Button

Compatibility alias for ComboBox.Trigger. Prefer ComboBox.Trigger in new code.

* required. Native HTML attributes of the underlying element are also accepted.

Clear

Optional button that resets the input value and clears the selection without stealing focus from the input. Disabled when there is nothing to clear.

* required. Native HTML attributes of the underlying element are also accepted.

Popover

Floating container for the options, positioned relative to the combobox input group. Composes Popover.Root and Popover.Content in non-modal mode.

* required. Native HTML attributes of the underlying element are also accepted.

List

Listbox bridge for the options. Delegates selection state and mode to ComboBox.Root and accepts additional ListBox.Root props such as class and emptyPlaceholder.

* required. Native HTML attributes of the underlying element are also accepted.

Item

A selectable option with combobox-specific filtering, virtual focus, and registration logic. Requires a unique id; use onAction for command-style items that run instead of selecting.

* required. Native HTML attributes of the underlying element are also accepted.

ItemIndicator

Visual selection indicator rendered inside ComboBox.Item. Defaults to a checkmark icon.

* required. Native HTML attributes of the underlying element are also accepted.

Status

* required. Native HTML attributes of the underlying element are also accepted.

Tags

Container that renders the selected values as tags in multiple mode. Supports an optional single-line overflow mode.

* required. Native HTML attributes of the underlying element are also accepted.

Tag

Visual token representing one selected value in multiple selection mode.

* required. Native HTML attributes of the underlying element are also accepted.

TagRemove

Button that removes its tag from the selection.

* required. Native HTML attributes of the underlying element are also accepted.