Combobox

Updated October 28, 2026

Combobox is a searchable select: type to filter its dithered listbox (in the field, or in the popup with a button trigger), arrows move the active option, and Enter or a click picks it. Leaving the field puts back the chosen label, so the value is always an option. Like the charts, it takes your theme's ink and paper, light or dark, and needs no Tailwind.

Example

Country

Market

Compare

FranceJapan

Region

Pick a region with data

Locked

import "@/components/dithercharts/controls.css"
import { Combobox } from "@/components/dithercharts/combobox"

<Combobox
  label="Country"
  placeholder="Search countries…"
  options={[
    { value: "ar", label: "Argentina" },
    { value: "au", label: "Australia" },
    { value: "br", label: "Brazil" },
    // …
  ]}
/>
// The search box moves into the popup, under a select-style button.
<Combobox label="Market" trigger="button" options={countries} />
// Several at once, as chips; the value is an array.
<Combobox label="Compare" multiple defaultValue={["fr", "jp"]} options={countries} />

Install

Controls install with DitherCharts Pro. See Installation to log in, then import controls.css once, e.g. in your root layout.

npx dithercharts add combobox

Props

It renders a native element, so every other attribute that element takes passes through.

Combobox props
Prop	Type	Default	Description
labelrequired	Type ReactNode	Default –	The caption above the field, and its accessible name.
optionsrequired	Type readonly ComboboxOption[]	Default –
multiple	Type boolean	Default `false`	Lets several options be chosen, shown as chips in the field; the value becomes an array.
value	Type string \| readonly string[]	Default –	The chosen value (an array when `multiple`), for a controlled combobox; pair it with `onValueChange`.
defaultValue	Type string \| readonly string[]	Default –	The value chosen at first (an array when `multiple`), for an uncontrolled combobox.
onValueChange	Type ((value: string) => void) \| ((value: string[]) => void)	Default –	Called with the chosen value, or "" when cleared; with `multiple`, the chosen values in option order.
trigger	Type "input" \| "button"	Default –	"input" (the default) types into the field itself. "button" shows the chosen label on a select-style button and puts the search box at the top of the popup. Not with `multiple`.
placeholder	Type string	Default "Search…", or "Select…" with a button trigger	Shown while nothing is chosen.
name	Type string	Default –	The form field name; a hidden input carries the value.
disabled	Type boolean	Default `false`
collisionPadding	Type { top?: number; bottom?: number }	Default 8 each	Space in px the popup keeps clear at the window's top and bottom, e.g. a sticky header's height. It opens on the side with more room and shrinks to fit.
className	Type string	Default –
hint	Type ReactNode	Default –	Help text under the field, read after its label.
error	Type ReactNode	Default –	An error under the field; it also marks the field invalid.