Combobox

Filters and selects an option from a listbox through one text field.

Preview

In action

Find

Studio city

Type to find the town. The list stays ink.

When to use

Use it for

One choice from a long list the user knows how to type: cities, people, tags.
searchText on an option when its label is not a plain string.

Not for

Short lists; use Select.
Free-form values not in the list; the combobox only picks options.

Install

Three ways in. They share one source, so the pixels match whichever you pick.

1. Import the package

npm install @noorddev/vlak-react

// once, next to your app's root
import "@noorddev/vlak-react/css";

import { Combobox } from "@noorddev/vlak-react";

Precompiled React and one stylesheet. No compiler to configure. Per-component imports work too: @noorddev/vlak-react/components/combobox.

2. Vendor the source

npx @noorddev/vlak-cli add combobox

The StyleX leaf lands in components/vlak/ with its dependencies, for your own compiler to own. See StyleX.

3. Through shadcn

npx shadcn add https://vlak.dev/r/combobox.json

The same registry item, installed by shadcn's CLI.

CSS only

<link rel="stylesheet" href="node_modules/@noorddev/vlak/css/vlak.css" />

No React. Link vlak.css and use the markup and classes below.

React

import { useState } from "react";
import { Combobox } from "@noorddev/vlak-react";

const [city, setCity] = useState("");

<Combobox
  aria-label="City"
  options={cities}
  value={city}
  onValueChange={setCity}
  placeholder="Search cities…"
  emptyLabel="No city matches."
/>

Props

Combobox

Editable combobox: the input holds focus, filters on typed text, and points at the active option with aria-activedescendant.

Prop	Type	Default
`options`required	`SelectOption[]`
`value`	`string`
`defaultValue`	`string`
`onValueChange`	`(value: string) => void`
`placeholder`	`string`	`"Search…"`
`emptyLabel`	`ReactNode`	`"Nothing found."`
`disabled`	`boolean`

Also accepts Omit<HTMLAttributes<HTMLDivElement>, "onChange" | "defaultValue">.

Keyboard

Keys	Does
`Type`	Filters the options and opens the list
`Arrow down`	Opens the list on the selected option, then moves down
`Arrow up`	Opens the list on the last option, then moves up
`Home, End`	First or last match
`Page up, Page down`	Moves ten matches
`Enter`	Picks the active match and closes
`Escape`	Clears the search and closes
`Tab`	Closes and moves on

Accessibility

APG editable combobox: an <input role="combobox"> with aria-autocomplete="list", aria-expanded, aria-controls, and aria-activedescendant; focus stays in the input.
The list is role="listbox" with role="option" rows carrying aria-selected; it does not open on focus alone.
Pass aria-label or aria-labelledby. Controlled with value and onValueChange, or uncontrolled with defaultValue.

Markup

<div class="rs-combobox"><input class="rs-input rs-input-full" role="combobox" placeholder="Search…" /><div class="rs-menu" role="listbox"><div class="rs-menu-item rs-menu-item-active" role="option" aria-selected="false">Alkmaar</div><div class="rs-menu-item" role="option" aria-selected="false">Amsterdam</div></div></div>

Classes

.rs-combobox.rs-combobox-empty

Depends on

/input /dropdown-menu