Next.js Combobox for the App Router

Drivn installs through a small CLI that writes the component source directly into your repository — there is no runtime npm package to version-lock. Open a terminal at the root of your Next.js 16 project and run npx drivn add combobox. The CLI prompts once for your install directory (defaulting to src/components/ui/), copies combobox.tsx, and adds its two dependencies to your package.json if they are missing: cmdk for the search list and keyboard navigation, and lucide-react for the chevron, search, check, and clear icons. The CLI reference documents every flag, including targeting a custom path or installing several components at once. After install you own the file — future Drivn releases will not overwrite it, and you can edit the internals without forking a package. Commit it to keep a clean baseline before customizing.

An App Router page is a server component by default, so it cannot call useState. Drivn's Combobox is marked 'use client' because it wraps cmdk, which tracks the search input and the open state on the client. The clean pattern is to keep the picker and its value in a small client component, then render that island inside an otherwise server-rendered page. Import Combobox from @/components/ui/combobox, hold the selected value in useState, and bind value and onChange. Compose Combobox.Trigger, Combobox.Content, Combobox.Empty, and a list of Combobox.Item. cmdk filters the items against the search field automatically — there is no manual filter callback. The trigger's children render the chosen label, so a common pattern is frameworks.find(f => f.value === value)?.label. The installation guide covers project bootstrapping.

Pass the multiple prop and the Combobox switches to multi-select: the value becomes a string[], and each selected value renders as a removable tag chip inside the trigger. Selecting an item that is already chosen toggles it off, so the same click both adds and removes from the array. Each chip carries an X icon from lucide-react whose onMouseDown calls e.stopPropagation() and e.preventDefault() before deselecting — that stops the click from also toggling the panel. Hold the value as a string[] in useState and the rest of the API is unchanged. The relevant slice of the trigger, copied verbatim from the source, is below.

The search field lives inside Combobox.Content, which mounts a cmdk instance with shouldFilter enabled, so typing scores every Combobox.Item against the query and hides non-matching rows without any state of your own. Wrap related items in Combobox.Group with a heading prop to render a labeled section, and drop Combobox.Separator between groups for a thin divider. The highlighted row uses data-[selected=true]:bg-accent from the styles object, so cmdk's keyboard navigation paints the active item as you arrow through the list. Add Combobox.Empty to control the no-results message, and pass an icon prop on any Combobox.Item — a component reference like icon={CircleDot} — to render an icon before the label. See the Combobox examples for the full set of patterns.

Unlike most comboboxes, the Drivn version does not pull in a popover primitive. The trigger is a plain <button> whose onClick toggles the open state, and the content sits in an absolutely positioned panel directly beneath it. Dismissal is handled by one effect in the source: a mousedown listener on document closes the panel when the click lands outside the component ref. The panel animates with transition-[opacity,scale] and toggles pointer-events-none while hidden, applying open ? 'opacity-100 scale-100' : 'opacity-0 scale-95 pointer-events-none' so it never intercepts clicks when closed. The chevron in the trigger rotates 180 degrees when open via open && 'rotate-180', or swaps for a clearable X when you pass the clearable prop and a value is set. The dismissal effect is below, copied from combobox.tsx.