Combobox

An editable input with local filtering and single selection.

When to use

Use a combobox when users need to search a known list before choosing one value. Prefer a native Select for short lists and an Input for unrestricted text. Use Menu for commands.

Class reference

ClassPurpose
.comboboxTheme scope around the labelled input and popup.
.form-controlExisting native input styles, including disabled and invalid states.
.combobox-panelAnchored, scrollable popup.
.combobox-optionOne plain-text choice with active, selected and disabled states.
.combobox-emptyMessage when filtering finds no matches.

Interactive

Search for “Ber”, choose a result with the keyboard or pointer, and try clearing and resetting the form. Vienna is disabled. The second field also accepts custom text. Each input submits its displayed text through its native name; this simple example does not map labels to separate IDs.

Type to filter, then use the arrow keys and Enter to choose a city.

Choose a city or enter a custom destination.

Type to filter, then use the arrow keys and Enter to choose a city.

Essential markup

Keep a visible label on the native input and a name on the listbox. Options contain plain text without interactive children. Put the empty message outside the listbox.

HTML
<div class="combobox" data-combobox>
	<label class="form-label" for="city">Destination</label>
	<input class="form-control" id="city" name="city" type="text" data-combobox-input />
	<button type="button" data-combobox-clear aria-label="Clear destination">Clear</button>
	<div class="combobox-panel" popover="manual" hidden data-combobox-panel>
		<div role="listbox" aria-label="Destination">
			<div class="combobox-option" role="option" aria-selected="false">Berlin</div>
			<div class="combobox-option" role="option" aria-selected="false">Hamburg</div>
		</div>
		<div class="combobox-empty" hidden data-combobox-empty>No matching cities.</div>
	</div>
</div>

Behavior and accessibility

  • Keep a visible label. The Showcase script manages combobox/listbox ARIA state while focus stays in the input.
  • Type to filter; arrows skip disabled options, Enter selects, and Escape, Tab or outside interaction closes the list.
  • Non-empty text must match an enabled option unless data-combobox-custom is set. Add required for mandatory input and data-combobox-invalid-message for a custom error. Applications provide .is-invalid, aria-invalid and linked feedback.
  • Selection and clearing emit input immediately. Typed edits retain native change on blur. Disable the clear button with its input; form reset restores defaults.

The package contains styles only; adapt src/scripts/combobox.ts for behavior. Keep options static; remote search and multiple selection are unsupported.

Responsive behavior

The popup matches the input width and flips or shifts to fit the viewport. Long lists scroll up to --combobox-max-height, keeping the active option visible. Native popover="manual" provides top-layer rendering; the fallback may be clipped by an ancestor. Use layout utilities for field width; RTL is supported.

CSS variables

Override these base defaults on the listed selector after the library styles. Variants and states may replace them; global tokens follow the active theme.

TokenDefaultPurposeScope / state
--combobox-max-height16remMaximum popup height before scrolling..combobox
--combobox-available-heightcalc(100vh - 1rem)Viewport space; updated by the positioning script..combobox
--combobox-paddingvar(--spacer-1)Padding inside the popup..combobox
--combobox-bg-colorvar(--bg-surface)Popup background..combobox
--combobox-colorvar(--text-color)Option text color..combobox
--combobox-border-colorvar(--border-color)Popup border color..combobox
--combobox-border-radiusvar(--border-radius)Popup corner radius..combobox
--combobox-box-shadowvar(--shadow-lg)Popup shadow..combobox
--combobox-active-bg-colorvar(--bg-surface-hover)Hovered and keyboard-active option background..combobox
--combobox-selected-colorvar(--action-color)Selected option text color..combobox
--combobox-z-indexvar(--z-index-tooltip)Popup stacking order for the fallback..combobox