Multi select

When to use #

Use it for

Assignees, filters and permissions where more than one value applies.
Space is tight and chips would wrap.

Skip it when

Only one value is allowed; use a select.
People add their own values; use tag input.

Installation #

terminal

pnpm dlx shadcn@latest add https://caliperui.site/r/multi-select.json

Adds its 3 files to components/ui/, each with its own stylesheet, and installs their packages. No account needed. The first part also adds Caliper UI’s tokens; import them once as in Installation.

Usage #

This is the code behind the preview above.

example.tsx

import { useState } from "react"
import { MultiSelect } from "@/components/ui/multi-select"

const team = [
  { value: "mara", label: "Mara Chen" },
  { value: "noor", label: "Noor Haddad" },
  { value: "ivo", label: "Ivo Petrov" },
  { value: "sana", label: "Sana Okafor" },
];

export function Assignees() {
  const [assignees, setAssignees] = useState(["mara", "noor", "ivo"]);
  return (
    <div className="w-full max-w-xs">
      <MultiSelect label="Assignees" options={team} value={assignees} onValueChange={setAssignees} />
    </div>
  );
}

API reference #

MultiSelect

component

PropTypeDefault

label *string—

options *readonly MultiSelectOption[]—

valuereadonly string[]—

defaultValuereadonly string[][]

onValueChange((value: string[]) => void)—

maxVisiblenumber2

placeholderstring"Select"

namestring—

disabledboolean—

classNamestring—

It exposes listbox and option semantics, with aria-label, aria-hidden, aria-haspopup, aria-expanded, aria-controls and aria-labelledby kept in step with state.

KeyBehaviour

↓Moves to the next item or value.

↑Moves to the previous item or value.

EscapeCloses or cancels, then returns focus to where it came from.

Motion #

It declares no animation in its component source. Any transition comes from its stylesheet, which uses the duration tokens that collapse to instant under prefers-reduced-motion.