# Shadcn Multi-Select
> Free shadcn/ui multi-select component for React — searchable, creatable tags, async loading, max items, grouped options and React Hook Form. The component shadcn/ui never shipped. Copy or install in one command.
Source: https://designrevision.com/components/multi-select
The **Shadcn Multi-Select** is the component shadcn/ui never shipped — a searchable dropdown for selecting **several** values, shown as removable tokens. Official shadcn/ui has a single-value [Select](/components/select) and a combobox *pattern*, but **no multi-select component**; this one fills that gap, built the shadcn way on the [Popover](/components/select) and Command primitives so it matches your existing UI. The examples below cover tags, async search, max items, grouping, and forms.
## When to use — multi-select vs combobox vs checkbox group
Reach for a multi-select when users choose **several** values from a list long enough to need search — skills, tags, assignees, categories. The selected values appear as removable badges, and typing filters the options. For picking a **single** value from the same searchable pattern, use a combobox. For a **short, always-visible** set of independent options, a [checkbox](/components/checkbox) group reads better than a dropdown.
## Creatable tags
Set `creatable` and the multi-select becomes a **tags input**: when the query matches no existing option, a "Create …" row appears, and selecting it adds the typed value. This is the pattern behind labels, topics, and free-form tagging — no separate component required.
## Async search
For directories or API-backed lists, pass an `onSearch` function that returns a `Promise` of options. The component **debounces** the query, shows a loading state, and remembers the labels of already-selected items so the tokens stay readable even as the option list changes underneath them.
## Max items and states
Cap the selection with `maxSelected` — once the limit is reached, the unselected options disable so users can't exceed it. Individual options can be `disabled` (never selectable) or `fixed` (selected and non-removable, e.g. a baseline permission), and the whole field accepts `disabled`.
## React Hook Form
The value is a plain `string[]`, so it drops into React Hook Form cleanly: read the field into `value` and write it back from `onChange`. Validate with a `zod` array schema like `z.array(z.string()).min(1)` and set `aria-invalid` on the field for the error styling. The React Hook Form example is a complete, working field.
## Accessibility
The trigger is a `role="combobox"` button with `aria-expanded`, and the list is the keyboard-navigable Command (arrow keys, type to filter, Enter to toggle, Escape to close). Each token's remove control carries an `aria-label`. Bind the field to a [Label](/components/label) with `htmlFor`/`id`, and link any error message with `aria-describedby`.
## Theming
The multi-select is assembled from the themed Popover, Command, and [Badge](/components/badge) primitives, so it reads your design tokens (`--primary`, `--popover`, `--input`, `--ring`) and follows your theme — including dark mode — with zero overrides.
## Installation
### multi-select
**Install:**
```bash
npx shadcn@latest add @designrevision/multi-select
```
**Dependencies:** lucide-react, popover, command, badge, utils
**Props**
| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| options * | MultiSelectOption[] | — | The available options. Each has value, label, and optional disabled, fixed, group, and icon. |
| value * | string[] | — | The selected values (controlled). |
| onChange * | (value: string[]) => void | — | Fires with the new array of selected values. |
| maxSelected | number | — | Caps how many items can be selected. |
| creatable | boolean | false | Allow creating new entries from the search query. |
| onSearch | (query: string) => Promise | — | Async option source — when set, options are fetched per (debounced) query. |
`*` required.
**Usage & accessibility:** A token-input multi-select built on Popover + Command + Badge. Set aria-invalid for the destructive error styling. Also accepts placeholder, disabled, emptyText, and loadingText.
```tsx
// components/ui/multi-select.tsx
"use client"
import * as React from "react"
import { CheckIcon, ChevronsUpDownIcon, XIcon } from "lucide-react"
import { cn } from "@/lib/utils"
import { Badge } from "@/components/ui/badge"
import {
Command,
CommandEmpty,
CommandGroup,
CommandInput,
CommandItem,
CommandList,
} from "@/components/ui/command"
import {
Popover,
PopoverContent,
PopoverTrigger,
} from "@/components/ui/popover"
export type MultiSelectOption = {
value: string
label: string
disabled?: boolean
/** Cannot be removed once selected. */
fixed?: boolean
/** Optional group heading the option is listed under. */
group?: string
/** Optional leading content (icon, avatar) shown in the list. */
icon?: React.ReactNode
}
export interface MultiSelectProps {
options: MultiSelectOption[]
value: string[]
onChange: (value: string[]) => void
placeholder?: string
/** Cap the number of selected items. */
maxSelected?: number
/** Allow creating new entries from the search query. */
creatable?: boolean
disabled?: boolean
className?: string
emptyText?: string
loadingText?: string
/** Async option source. When provided, options are fetched per query. */
onSearch?: (query: string) => Promise
id?: string
"aria-invalid"?: boolean
"aria-describedby"?: string
}
export function MultiSelect({
options: optionsProp,
value,
onChange,
placeholder = "Select…",
maxSelected,
creatable = false,
disabled = false,
className,
emptyText = "No results.",
loadingText = "Loading…",
onSearch,
id,
"aria-invalid": ariaInvalid,
"aria-describedby": ariaDescribedby,
}: MultiSelectProps) {
const [open, setOpen] = React.useState(false)
const [query, setQuery] = React.useState("")
const [asyncOptions, setAsyncOptions] = React.useState([])
const [loading, setLoading] = React.useState(false)
const labels = React.useRef(new Map())
const options = onSearch ? asyncOptions : optionsProp
// Remember labels so selected tokens stay readable even after the
// (async) option list changes.
React.useEffect(() => {
for (const option of [...optionsProp, ...asyncOptions]) {
labels.current.set(option.value, option.label)
}
}, [optionsProp, asyncOptions])
// Resolve a value's label synchronously (so tokens render correctly on the
// first paint), falling back to the remembered cache and then the raw value.
const labelFor = (val: string) =>
optionsProp.find((option) => option.value === val)?.label ??
asyncOptions.find((option) => option.value === val)?.label ??
labels.current.get(val) ??
val
// Debounced async search.
React.useEffect(() => {
if (!onSearch || !open) return
let active = true
setLoading(true)
const timer = setTimeout(() => {
onSearch(query).then((result) => {
if (!active) return
setAsyncOptions(result)
setLoading(false)
})
}, 300)
return () => {
active = false
clearTimeout(timer)
}
}, [query, onSearch, open])
const atMax = maxSelected != null && value.length >= maxSelected
const isFixed = (val: string) =>
optionsProp.find((option) => option.value === val)?.fixed ?? false
const toggle = (val: string) => {
if (value.includes(val)) {
if (isFixed(val)) return
onChange(value.filter((item) => item !== val))
} else if (!atMax) {
onChange([...value, val])
}
}
const create = () => {
const next = query.trim()
if (!next || atMax || value.includes(next)) return
labels.current.set(next, next)
onChange([...value, next])
setQuery("")
}
const groups = React.useMemo(() => {
const map = new Map()
for (const option of options) {
const key = option.group ?? ""
if (!map.has(key)) map.set(key, [])
map.get(key)!.push(option)
}
return Array.from(map.entries())
}, [options])
const canCreate =
creatable &&
query.trim() !== "" &&
!atMax &&
!options.some(
(option) => option.label.toLowerCase() === query.trim().toLowerCase()
) &&
!value.includes(query.trim())
return (
{loading ? (