Combobox

Searchable selection input that combines free-form filtering with a structured list of options for large or descriptive datasets.

AccessibleDark ModeKeyboard NavAnimated

Install

$npx react-principles add combobox

Live Demo

Open in Storybookopen_in_new

Framework

expand_more

Search and select a frontend stack.

Selected value: next

Code Snippet

src/ui/Combobox.tsx

import { Combobox } from "@/ui/Combobox";

<Combobox
  options={frameworks}
  value={framework}
  onValueChange={setFramework}
  label="Framework"
  description="Search and select a frontend stack."
/>

Copy-Paste (Single File)

Combobox.tsx

import { useEffect, useMemo, useRef, useState } from "react";
import { cn } from "@/lib/utils";

export interface ComboboxOption {
  label: string;
  value: string;
  description?: string;
  disabled?: boolean;
}

export interface ComboboxProps {
  options: ComboboxOption[];
  value?: string;
  defaultValue?: string;
  onValueChange?: (value: string) => void;
  placeholder?: string;
  emptyText?: string;
  label?: string;
  description?: string;
  className?: string;
}

Props

Prop	Type	Default	Description
`options`	`ComboboxOption[]`	`—`	Available options shown in the floating results list.
`value`	`string`	`—`	Controlled selected option value.
`defaultValue`	`string`	`—`	Initial selected option value when uncontrolled.
`onValueChange`	`(value: string) => void`	`—`	Called when users pick a result.
`placeholder`	`string`	`"Search..."`	Input placeholder text before search begins.
`emptyText`	`string`	`"No results"`	Fallback message when filtering returns no matches.
`label`	`string`	`—`	Optional field label shown above the input.
`description`	`string`	`—`	Helper text displayed below the combobox.
`className`	`string`	`—`	Additional classes applied to the root wrapper.

react-principles