How to Add a Combobox to a React App

Before installing the Combobox, confirm your React project has the three things Drivn assumes: Tailwind CSS v4 installed and processing your CSS, TypeScript configured (the component ships as a .tsx file), and a @/ path alias pointing at your source directory. If you scaffolded with create-next-app, npm create vite, or npx drivn@latest create, all three are already wired. The Combobox is one of the few Drivn components with a runtime dependency beyond lucide-react: it imports Command as CommandPrimitive from cmdk for the searchable list and keyboard handling. The CLI installs cmdk automatically when you add the component, so there is nothing to add by hand — the installation page lists the minimal config if you are wiring a custom setup.

Run the CLI from your project root to add the Combobox source file. The command prompts once for your install directory (defaulting to src/components/ui/), writes combobox.tsx, and adds cmdk and lucide-react to your package.json if they are not already present. No global config file is created — the Combobox is a single TypeScript file in your repo that you edit like any other component. The icons it pulls from lucide-react are ChevronDown, X, Check, and Search, used for the trigger chevron, the clear button, the selected tick, and the search field. Confirm the file landed in your editor, then commit it. The CLI docs cover the flags for targeting a custom location during install.

Import the Combobox and compose it from its sub-components. Hold the selected value in useState, pass it as value, and pass your setter as onChange. The Combobox.Trigger shows the current selection (look it up from your options array) and a placeholder when empty; Combobox.Content mounts the searchable list with its own placeholder for the search field. Each Combobox.Item takes a value and renders a Check icon when it is the selected one. The cmdk engine inside Content filters items as the user types, and selecting an item in single mode calls onChange and closes the popover automatically. Because the source is 'use client', render it inside a client component in a Next.js App Router app. See the Combobox docs for the full prop table.

Pass multiple to the root and the value becomes a string[]. In multiple mode, selecting an item toggles it in the array — the source runs arr.includes(v) ? arr.filter((i) => i !== v) : [...arr, v] — and the popover stays open so the user can pick several. The Combobox.Trigger renders the selected values as tags when you map them inside it, and passing clearable to the trigger shows an X button that calls onClear to reset the selection to an empty array. Initialize your state as useState<string[]>([]) so the types line up. Each selected item still shows its Check icon in the list, and the search input keeps filtering as you go.

For longer lists, wrap items in Combobox.Group with a heading and separate sections with Combobox.Separator. Each Combobox.Item accepts an icon prop that takes a component reference (icon={Globe}) and renders it before the label — the same icon-as-component pattern Drivn uses across its components. The Combobox.Empty element renders inside the list and, thanks to cmdk, shows automatically when the search query matches nothing; pass children to customize the text or leave it for the default "No results found." To restyle, open src/components/ui/combobox.tsx and edit the styles object — item controls the row (it reads data-[selected=true]:bg-accent from cmdk), content controls the popover, and every class reads your Tailwind tokens, so a theme change in globals re-themes every Combobox at once. See the Combobox examples for grouped lists and async data.