Docs

Organisms

Combobox

Autocomplete search input paired with a selectable dropdown list.

5 examplesComposite ComponentReact 19 & Next.js 16Tailwind CSS v4
Install
pnpm add @quinkit/ui cmdk
Import
import { Combobox } from "@quinkit/ui";

Required packages

Powers Command and Combobox. Add these packages before using this component:

  • @quinkit/ui
  • cmdk

Install command is shown above. Without the peer package, imports will fail at build time.

Interactive Examples

Live previews · code · themes · viewport · dark mode

Basic Searchable Select

The Combobox component with searchable options.

Basic Searchable Select rendered preview

Multi-Select with Tags

Select multiple values shown as removable tags.

Multi-Select with Tags rendered preview

Async Options Loading

Load options dynamically on open with a loading spinner.

Async Options Loading rendered preview

Command-Style Grouped Items

Group search options into labelled category headings.

Command-Style Grouped Items rendered preview

Form Integration

Combobox input field inside a standard configuration form.

Form Integration rendered preview

Framework Selection

Choose project target framework.

Overview

Combobox is an accessible, searchable select input composed from Radix Popover and Command. It supports type-to-filter option searching, selection indicators, custom empty state feedback, and responsive trigger popover matching.

Installation

bash
pnpm add @quinkit/ui cmdk

cmdk is a required peer dependency for Combobox (via Command).

Usage Examples

### Basic Usage

tsx
import { useState } from "react";
import { Combobox } from "@quinkit/ui";

const frameworks = [
  { value: "next", label: "Next.js 16" },
  { value: "react", label: "React 19" },
  { value: "vite", label: "Vite" }
];

export function ComboboxDemo() {
  const [val, setVal] = useState("next");
  return <Combobox options={frameworks} value={val} onValueChange={setVal} />;
}

Props

PropTypeDefaultDescription
optionsComboboxOption[]**Required**List of { value, label } options.
valuestringundefinedSelected option value.
onValueChange(value: string) => voidundefinedCallback fired on option selection.
placeholderstring"Select option..."Trigger button placeholder text.
searchPlaceholderstring"Search options..."Search field input placeholder text.
emptyTextstring"No option found."Message displayed when search yields zero matches.
disabledbooleanfalseDisable combobox trigger interaction.
classNamestringundefinedAdditional class names.

Accessibility Details

  • Trigger element acts as a combobox button with aria-expanded attributes.
  • Type-ahead keyboard navigation filters list items dynamically.
  • Escape key closes dropdown panel.

Accessibility & Keyboard

Combobox adheres to WAI-ARIA design patterns for accessible web components.

Keyboard Navigation

  • Tab / Shift + Tab — Focuses control and moves between interactive elements.
  • Space / Enter — Triggers action or toggles selection.
  • Escape — Closes open popovers, overlays, or dropdown menus.

ARIA Standards

  • Built with semantic HTML tags and explicit aria-* attributes.
  • Uses high-contrast focus rings (ring-ring) visible in both light & dark mode.
  • Supports screen readers with non-visual label fallbacks.

Registry Install

Add a shadcn-compatible bridge file to your project that re-exports from @quinkit/ui.

Registry
npx shadcn@latest add https://quinkit-ui.vercel.app/r/combobox.json