Combobox

A filterable single-value picker on the ARIA combobox pattern.

import { Combobox, VStack } from "astralis-ui";

const FRAMEWORKS = [
  { label: "Next.js", value: "next" },
  { label: "Remix", value: "remix" },
  { label: "Astro", value: "astro" },
  { label: "Vite", value: "vite" },
  { label: "Gatsby", value: "gatsby", disabled: true },
];

const GROUPED = [
  { group: "Planets", options: [
    { label: "Mercury", value: "mercury" },
    { label: "Venus", value: "venus" },
    { label: "Mars", value: "mars" },
  ]},
  { group: "Moons", options: [
    { label: "Europa", value: "europa" },
    { label: "Titan", value: "titan" },
  ]},
];

export function ComboboxDemo() {
  return (
    <VStack gap="4" alignItems="stretch" className="astralis:w-full astralis:max-w-sm">
      <Combobox options={FRAMEWORKS} placeholder="Pick a framework…" clearable />
      <Combobox options={GROUPED} placeholder="Grouped options…" defaultValue="europa" clearable />
    </VStack>
  );
}

Import#

import { Combobox } from "astralis-ui";

Type to filter, arrows to move, Enter to commit, Escape to revert to the last committed selection. Reopening on a committed value shows the full list — filtering only kicks in once you type.

Compared to Select: Select is a button you pick from; Combobox is an input you search in. For multiple values, use MultiSelect. All three share the same option machinery, so options shapes are interchangeable.

Props#

Prop	Type	Default	Description
`options`	`Array<{label, value, disabled?} \| {group, options}>`	`[]`	Flat or grouped options.
`value` / `defaultValue`	`string \| number \| null`	—	Controlled / uncontrolled selection.
`onChange`	`(value) => void`	—	Fires on commit (pick or clear).
`onInputChange`	`(text) => void`	—	Fires on every filter keystroke.
`clearable`	`boolean`	`false`	✕ button when a value is selected.
`name`	`string`	—	Hidden input for native form submission.
`emptyText`	`string`	`"No matches"`	Shown when nothing matches.
`size` / `variant` / `colorScheme` / `invalid` / `disabled` / `readOnly` / `loading`	—	as Select	Shared styling + state system.

Keyboard#

Key	Action
type	Filter the options
`↓`	Open when closed; move the highlight down
`↑`	Move the highlight up
`Enter`	Commit the highlighted option
`Esc`	Close and revert to the last committed value
`Tab`	Close, revert, and move on

Accessibility#

role="combobox" with aria-autocomplete="list", aria-expanded, aria-controls and aria-activedescendant tracking the highlighted option — the screen reader follows the highlight while focus stays in the input. Label/description wiring comes from Field.