Skip to content
Aback UI

Forms

Combobox

A searchable single-select field built on Popover and Command.

BetaNew shared patternRegistry JSON (opens in a new tab)
Review owner

Grace Hopper · Infrastructure

Installation

Copy the source with the CLI to own and edit it, or import it from the npm package.

npx aback-ui@latest add combobox

Writes components/ui/combobox.tsx and the components it builds on. First time in this project? Run npx aback-ui@latest init first, as the installation guide shows.

Usage

Import the parts you need from the installed file. The Code tab above has a complete, working example.

tsx
import { Combobox } from "@/components/ui/combobox";

API reference

Props and composition points for Combobox. Native element props pass through.

PropTypeDefaultDescription
optionsComboboxOption[]NoneThe list: { value, label, description?, disabled?, keywords? }. Labels are visible and searchable; keywords add hidden search terms.
value / onValueChangestring | undefined / (value: string) => voidNoneControlled selection. The component renders the matching option's label, so the consumer keeps owning the value.
placeholderstring"Select an option"Shown on the trigger when no option is selected.
searchPlaceholder / emptyMessagestring / stringNoneCopy for the search field and the no-results state. Give a recovery hint rather than only saying nothing matched.
disabledbooleanNoneDisables the trigger. Use aria-describedby to explain why when the reason is not obvious.
namestringNoneRenders a hidden input with the selected value so the field submits with a native form.
aria-label / aria-labelledby / aria-describedby / aria-invalidstring / string / string / booleanNoneNames the trigger and dialog and connects help or error text. Pass a visible label through aria-labelledby when one is present.
className / triggerClassName / alignstring / string / "start" | "center" | "end"NoneLayout and placement hooks; the selected state and keyboard behavior stay intact.

Dependencies: @tabler/icons-react, plus the shared @/lib/utils helper.

Accessibility

Semantics, keyboard behavior, and the decisions that keep the component operable.

  • The trigger is a button with aria-haspopup=listbox and aria-expanded, so the closed field is announced as a control, not a text input.
  • The search field is the combobox and owns the listbox. Arrow keys, Home, End, Enter, and Escape operate the list.
  • The selected option is marked with a check icon and aria-selected; the check is hidden from assistive technology so the announcement is not doubled.
  • Disabled options stay in the list with aria-disabled, so the option set does not change shape between searches.
  • The trigger keeps its value label; nothing relies on placeholder text alone to explain the field.

Keyboard

KeyAction
EnterorSpaceOpen the list from the trigger.
Arrow DownorArrow UpMove through the filtered options.
HomeorEndJump to the first or last option.
EnterSelect the active option and close the list.
EscapeClose the list and return focus to the trigger.

Use Combobox when the option set is long enough to need search. For a short, fixed set, the native Select is simpler and keeps the platform's mobile picker.

Used in production

The Aback products whose interfaces shaped this component.

This component is new in Aback UI. It has not shipped in an Aback product yet, so no production use is claimed.

Related