Combobox

Searchable single- or multi-select field with static or API-loaded options and Form autosave support.

Installation

bash

pnpm dlx shadcn@latest add @cs/combobox

Usage

tsx

import { Combobox } from "@/components/cs/combobox"

tsx

<Combobox
  label="Country"
  name="country"
  options={[{ id: "cz", name: "Czechia" }, { id: "de", name: "Germany" }]}
  translations={{ placeholder: "Choose a country", nothingFound: "No countries found" }}
/>

Translated option labels

Uses `optionsKey` and `tFunction` to derive each option label from its ID.

tsx

"use client"

import { Combobox } from "@/registry/cs/ui/combobox"
import { NextIntlClientProvider } from "next-intl"
import { PreviewPanel } from "./preview-utils"
import { toast } from "../ui/toast"

const statusOptions = [{ id: "draft" }, { id: "review" }, { id: "published" }]

const statusLabels: Record<string, string> = {
	draft: "Draft",
	review: "Ready for review",
	published: "Published",
}

export default function ComboboxTranslationPreview() {
	return (
		<NextIntlClientProvider locale="en" messages={{ status: statusLabels }}>
			<PreviewPanel>
				<Combobox
					name="status"
					label="Publication status"
					options={statusOptions}
					defaultValue="review"
					translations={{
						placeholder: "Choose a status",
						nothingFound: "No statuses found",
						optionsKey: "status",
					}}
					onString={(value) => toast.info(value ?? "No status selected")}
				/>
			</PreviewPanel>
		</NextIntlClientProvider>
	)
}

API Reference

ComboboxOption

A selectable item rendered by Combobox.

tsx

type ComboboxOption = {
	/** Stable value submitted when this option is selected. */
	id: TValue
	/** Primary option label. Defaults to the string representation of `id`. */
	name?: string
	/** Supporting text displayed below the option label. */
	desc?: string
	/** Secondary content aligned alongside the option label. */
	secondary?: ReactNode
}

Combobox

Searchable single- or multi-select field with static or API-loaded options. It keeps the selected values in hidden inputs, integrates with Form autosave, and uses useSelectOptions to debounce optional remote searches.

Props

Name	Type	Default	Description
align	"center" \| "end" \| "start"	-	Horizontal alignment of the options popover.
className	string	-	Additional classes applied to the field wrapper and trigger button.
comboboxClassName	string	-	Additional classes applied to the popup search input.
defaultValue	TValue	-	Initial selected value for uncontrolled usage.
disabled	boolean	-	Prevents selection and text input.
error	string \| null	-	Validation error message for the field.
fetchOptions	SelectFetchOptions	-	Remote option endpoint configuration.
id	string	-	DOM id assigned to the combobox input.
label	ReactNode	-	Label displayed above the combobox.
multiple	false	-	Enables multi-selection.
name	string	"combobox"	Name used for hidden form inputs.
onNumber	(value: number \| null) => void	-	Called when a numeric option is selected or cleared.
onString	(value: string \| null) => void	-	Called when a string option is selected or cleared.
options	ComboboxOption<TValue>[]	-	Static options displayed in the menu.
required	boolean	false	Requires a value before the form can submit.
searchOnly	boolean	false	Shows search results without retaining a selected value.
title	string	-	Accessible title for the combobox input.
translations *	{ empty?: string placeholder: string nothingFound: string optionsKey?: string }	-	Text used for the empty selection, input placeholder, and empty result state.
value	TValue	-	Controlled selected value.

Dependencies

cn next-intl @cs/field @cs/form @cs/use-select-options @shadcn/combobox @shadcn/field @shadcn/item @shadcn/utils