{
  "schemaVersion": 1,
  "target": "react",
  "name": "multi-select",
  "version": "0.1.0",
  "category": "forms",
  "title": "Multi Select",
  "description": "Pick several options as removable chips, with type-ahead filtering, a selection limit, and a tag mode that adds new values, where chips scale in and the rest slide aside.",
  "tags": [
    "form",
    "multi-select",
    "chips",
    "tags",
    "combobox",
    "base-ui"
  ],
  "requires": {
    "projectTypes": [
      "next",
      "vite-react"
    ],
    "styling": "tailwind-v4"
  },
  "npmDependencies": {
    "@base-ui/react": "^1.9.0",
    "motion": "^14.14.0"
  },
  "registryDependencies": [],
  "docsPath": "/components/multi-select",
  "props": [
    {
      "name": "options",
      "type": "{ value, label, description?, icon?, disabled? }[]",
      "description": "The options to pick from."
    },
    {
      "name": "value / defaultValue",
      "type": "string[]",
      "description": "Selected values, in the order they were picked."
    },
    {
      "name": "onValueChange",
      "type": "(value: string[]) => void",
      "description": "Called with the new selection."
    },
    {
      "name": "creatable",
      "type": "boolean",
      "default": "false",
      "description": "Tag mode: a value that is not in the list can be added with Enter, a comma, or the Add row."
    },
    {
      "name": "max",
      "type": "number",
      "description": "Most values that can be picked. Shows a count and disables the rest once full."
    },
    {
      "name": "placeholder",
      "type": "string",
      "default": "\"Select…\"",
      "description": "Shown while nothing is selected."
    },
    {
      "name": "emptyMessage",
      "type": "ReactNode",
      "default": "\"No matches\"",
      "description": "Shown when the query matches nothing."
    },
    {
      "name": "name",
      "type": "string",
      "description": "Submits each value under this name in a form."
    },
    {
      "name": "label / description / error",
      "type": "ReactNode",
      "description": "Label, helper text, and an error that marks the field invalid."
    }
  ],
  "accessibility": [
    "Built on Base UI Combobox in multiple mode: the input is role=\"combobox\" with a listbox of options; arrow keys move the highlight and Enter toggles an option.",
    "Backspace at the start of the input removes the last chip; Left Arrow moves onto the chips, and each chip has a remove button labeled Remove <name>.",
    "The input describes how many are selected, the limit when there is one, and how to reach the chips.",
    "Escape closes the list and clears the query without dropping the selection.",
    "Chips scale in and siblings slide with transforms only; with reduced motion preferred they appear and leave in place."
  ],
  "states": [
    "empty",
    "open",
    "filtering",
    "selected",
    "at limit",
    "creating",
    "invalid",
    "disabled"
  ],
  "files": [
    {
      "path": "ui/multi-select.tsx",
      "content": "\"use client\";\n\nimport { Combobox } from \"@base-ui/react/combobox\";\nimport { AnimatePresence, MotionConfig, motion } from \"motion/react\";\nimport { type KeyboardEvent, type ReactNode, useId, useMemo, useState } from \"react\";\n\nfunction cx(...classes: (string | false | null | undefined)[]) {\n  return classes.filter(Boolean).join(\" \");\n}\n\nexport interface MultiSelectOption {\n  /** Stored in the value array. Must be unique. */\n  value: string;\n  /** Shown in the list and on the chip. */\n  label: string;\n  /** Secondary text at the end of the row, such as a role or a count. */\n  description?: string;\n  /** A 16px icon or avatar shown in the row and on the chip. */\n  icon?: ReactNode;\n  /** Shown but cannot be picked. */\n  disabled?: boolean;\n}\n\ninterface ViewItem extends MultiSelectOption {\n  /** Set on the synthetic \"Create\" row in creatable mode. */\n  create?: boolean;\n}\n\nexport interface MultiSelectProps {\n  /** The options to pick from. */\n  options: MultiSelectOption[];\n  /** The selected values. Pass with `onValueChange` to control them. */\n  value?: string[];\n  /** The starting selection when uncontrolled. */\n  defaultValue?: string[];\n  /** Called with the new selection, in the order it was picked. */\n  onValueChange?: (value: string[]) => void;\n  /** Visible label. Pass `aria-label` instead when the label is shown elsewhere. */\n  label?: ReactNode;\n  /** Names the field for screen readers when there is no visible label. */\n  \"aria-label\"?: string;\n  /** Helper text below the field. */\n  description?: ReactNode;\n  /** Error message. Marks the field invalid and replaces the description. */\n  error?: ReactNode;\n  /** Shown while nothing is selected. */\n  placeholder?: string;\n  /** Tag input mode: typing a value that is not in the list offers to add it. Enter or a comma adds it. */\n  creatable?: boolean;\n  /** The most values that can be picked. Further options are disabled until one is removed. */\n  max?: number;\n  /** Shown when nothing matches the query. */\n  emptyMessage?: ReactNode;\n  /** Submits each value under this name inside a form. */\n  name?: string;\n  disabled?: boolean;\n  required?: boolean;\n  id?: string;\n  /** Classes for the wrapping element. */\n  className?: string;\n}\n\nconst spring = { type: \"spring\", duration: 0.32, bounce: 0 } as const;\n\nfunction RemoveIcon() {\n  return (\n    <svg aria-hidden=\"true\" viewBox=\"0 0 16 16\" fill=\"none\">\n      <path d=\"M5 5l6 6M11 5l-6 6\" stroke=\"currentColor\" strokeWidth=\"1.5\" strokeLinecap=\"round\" />\n    </svg>\n  );\n}\n\nfunction ChevronIcon() {\n  return (\n    <svg aria-hidden=\"true\" viewBox=\"0 0 16 16\" fill=\"none\">\n      <path d=\"M5.5 6.25L8 3.75l2.5 2.5M5.5 9.75L8 12.25l2.5-2.5\" stroke=\"currentColor\" strokeWidth=\"1.5\" strokeLinecap=\"round\" strokeLinejoin=\"round\" />\n    </svg>\n  );\n}\n\nconst iconButton = cx(\n  \"flex size-7 shrink-0 cursor-default items-center justify-center rounded-md text-zinc-400 dark:text-zinc-500\",\n  \"hover:bg-zinc-950/[0.04] hover:text-zinc-700 dark:hover:bg-white/[0.06] dark:hover:text-zinc-200\",\n  \"transition-colors duration-150 ease-out motion-reduce:transition-none\",\n  \"focus-visible:outline-2 focus-visible:outline-solid focus-visible:-outline-offset-2 focus-visible:outline-sky-500 [&_svg]:size-4\",\n);\n\n/**\n * Picks several options, shown as removable chips in the field. Typing filters the list; arrow\n * keys move through options, Left Arrow moves onto the chips, and Backspace removes the last one.\n * Chips scale in where they land and the rest slide aside, so the field never jumps. Set\n * `creatable` for a tag input and `max` to cap the selection.\n */\nexport function MultiSelect({\n  options,\n  value: valueProp,\n  defaultValue = [],\n  onValueChange,\n  label,\n  \"aria-label\": ariaLabel,\n  description,\n  error,\n  placeholder = \"Select…\",\n  creatable = false,\n  max,\n  emptyMessage = \"No matches\",\n  name,\n  disabled,\n  required,\n  id,\n  className,\n}: MultiSelectProps) {\n  const generatedId = useId();\n  const inputId = id ?? generatedId;\n  const messageId = `${inputId}-message`;\n  const invalid = error != null && error !== false;\n  const message = invalid ? error : description;\n\n  const [innerValue, setInnerValue] = useState<string[]>(defaultValue);\n  const values = valueProp ?? innerValue;\n  const [created, setCreated] = useState<MultiSelectOption[]>([]);\n  const [query, setQuery] = useState(\"\");\n\n  const known = useMemo(() => {\n    const map = new Map<string, MultiSelectOption>();\n    for (const option of [...options, ...created]) map.set(option.value, option);\n    return map;\n  }, [options, created]);\n  const selected = values.map((value) => known.get(value) ?? { value, label: value });\n  const full = max != null && values.length >= max;\n\n  const trimmed = query.trim();\n  const exact = trimmed ? [...known.values()].find((option) => option.label.toLocaleLowerCase() === trimmed.toLocaleLowerCase()) : undefined;\n  const items: ViewItem[] = [...options, ...created.filter((option) => !options.some((o) => o.value === option.value))];\n  if (creatable && trimmed && !exact && !full) items.push({ value: trimmed, label: trimmed, create: true });\n\n  function commit(next: string[]) {\n    if (valueProp === undefined) setInnerValue(next);\n    onValueChange?.(next);\n  }\n\n  function add(text: string) {\n    const option = exact ?? { value: text, label: text };\n    if (!exact) setCreated((list) => [...list, option]);\n    if (!values.includes(option.value) && !full) commit([...values, option.value]);\n    setQuery(\"\");\n  }\n\n  function handleKeyDown(event: KeyboardEvent<HTMLInputElement>) {\n    if (creatable && event.key === \",\" && trimmed) {\n      event.preventDefault();\n      add(trimmed);\n    }\n  }\n\n  return (\n    <MotionConfig reducedMotion=\"user\">\n      <Combobox.Root<ViewItem, true>\n        items={items}\n        multiple\n        value={selected}\n        onValueChange={(next, details) => {\n          // Escape on a closed list would wipe every chip; in a multi-select it only clears the query.\n          if (details.reason === \"escape-key\") {\n            setQuery(\"\");\n            return;\n          }\n          const creation = next.find((item) => item.create);\n          if (creation) {\n            add(creation.label);\n            return;\n          }\n          commit(next.map((item) => item.value));\n          setQuery(\"\");\n        }}\n        inputValue={query}\n        onInputValueChange={setQuery}\n        isItemEqualToValue={(item, current) => item.value === current.value}\n        itemToStringLabel={(item) => item.label}\n        itemToStringValue={(item) => item.value}\n        autoHighlight\n        name={name}\n        disabled={disabled}\n        required={required}\n      >\n        <div className={cx(\"grid gap-1.5\", className)}>\n          {label || max != null ? (\n            <div className=\"flex items-baseline justify-between gap-3\">\n              {label ? (\n                <label htmlFor={inputId} className=\"text-sm font-medium text-zinc-900 dark:text-zinc-100\">\n                  {label}\n                </label>\n              ) : (\n                <span />\n              )}\n              {max != null ? (\n                <span aria-hidden=\"true\" className={cx(\"font-mono text-xs tabular-nums\", full ? \"text-zinc-950 dark:text-white\" : \"text-zinc-500\")}>\n                  {values.length}/{max}\n                </span>\n              ) : null}\n            </div>\n          ) : null}\n          <Combobox.InputGroup\n            className={cx(\n              \"relative flex min-h-9 w-full cursor-text items-start gap-1 rounded-lg border bg-white py-1 pr-1 pl-1 text-sm shadow-[0_1px_2px_rgb(0_0_0/0.04)] dark:bg-black dark:shadow-none\",\n              \"transition-[border-color,box-shadow] duration-150 ease-out motion-reduce:transition-none\",\n              invalid\n                ? \"border-red-500/60 focus-within:border-red-500 focus-within:ring-3 focus-within:ring-red-500/20\"\n                : \"border-zinc-950/15 hover:border-zinc-950/25 focus-within:border-sky-500 focus-within:ring-3 focus-within:ring-sky-500/20 dark:border-white/15 dark:hover:border-white/25 dark:focus-within:border-sky-500\",\n              \"data-[disabled]:cursor-not-allowed data-[disabled]:opacity-60\",\n            )}\n          >\n            <Combobox.Chips\n              aria-label={selected.length > 0 ? `Selected${typeof label === \"string\" ? ` ${label.toLowerCase()}` : \"\"}` : undefined}\n              className=\"flex min-w-0 flex-1 flex-wrap items-center gap-1\"\n            >\n              <AnimatePresence initial={false} mode=\"popLayout\">\n                {selected.map((item) => (\n                  <Combobox.Chip\n                    key={item.value}\n                    aria-label={item.label}\n                    aria-description=\"Press Backspace or Delete to remove\"\n                    render={\n                      <motion.div\n                        layout=\"position\"\n                        initial={{ opacity: 0, scale: 0.85, filter: \"blur(2px)\" }}\n                        animate={{ opacity: 1, scale: 1, filter: \"blur(0px)\" }}\n                        exit={{ opacity: 0, scale: 0.85, filter: \"blur(2px)\", transition: { duration: 0.14, ease: \"easeOut\" } }}\n                        transition={spring}\n                      />\n                    }\n                    className={cx(\n                      \"flex h-6.5 max-w-full cursor-default items-center gap-1.5 rounded-md pr-0.5 pl-2 text-[13px] leading-none outline-hidden\",\n                      \"bg-zinc-950/[0.05] text-zinc-800 dark:bg-white/[0.08] dark:text-zinc-100\",\n                      \"focus-within:bg-zinc-950/[0.1] focus-within:shadow-[inset_0_0_0_1px_rgb(9_9_11/0.25)] dark:focus-within:bg-white/[0.14] dark:focus-within:shadow-[inset_0_0_0_1px_rgb(255_255_255/0.3)]\",\n                      \"data-[highlighted]:bg-zinc-950/[0.1] dark:data-[highlighted]:bg-white/[0.14]\",\n                      item.icon != null && \"pl-1\",\n                    )}\n                  >\n                    {item.icon != null ? (\n                      <span aria-hidden=\"true\" className=\"flex size-4 shrink-0 items-center justify-center [&_svg]:size-3.5\">\n                        {item.icon}\n                      </span>\n                    ) : null}\n                    <span className=\"truncate\">{item.label}</span>\n                    <Combobox.ChipRemove\n                      aria-label={`Remove ${item.label}`}\n                      className={cx(\n                        \"flex size-5 shrink-0 cursor-default items-center justify-center rounded-[5px] text-zinc-400 outline-hidden dark:text-zinc-500\",\n                        \"hover:bg-zinc-950/[0.08] hover:text-zinc-900 dark:hover:bg-white/[0.12] dark:hover:text-white\",\n                        \"transition-colors duration-150 ease-out motion-reduce:transition-none [&_svg]:size-3.5\",\n                      )}\n                    >\n                      <RemoveIcon />\n                    </Combobox.ChipRemove>\n                  </Combobox.Chip>\n                ))}\n                <motion.span key=\"__input\" layout=\"position\" transition={spring} className={cx(\n                    \"flex flex-1\",\n                    // At rest the input tucks in after the last chip; it claims room for typing once focused.\n                    selected.length > 0 ? \"min-w-2 focus-within:min-w-20\" : \"min-w-20\",\n                  )}>\n                  <Combobox.Input\n                    id={inputId}\n                    aria-label={label ? undefined : ariaLabel}\n                    aria-invalid={invalid || undefined}\n                    aria-describedby={message ? messageId : undefined}\n                    aria-description={\n                      selected.length > 0\n                        ? `${selected.length}${max != null ? ` of ${max}` : \"\"} selected. From the start of the input, press Left Arrow to move to the selected items.`\n                        : max != null\n                          ? `Pick up to ${max}.`\n                          : undefined\n                    }\n                    placeholder={selected.length > 0 ? undefined : placeholder}\n                    onKeyDown={handleKeyDown}\n                    className=\"h-6.5 w-full min-w-0 bg-transparent px-1.5 text-sm text-zinc-950 outline-hidden placeholder:text-zinc-400 disabled:cursor-not-allowed dark:text-white dark:placeholder:text-zinc-500\"\n                  />\n                </motion.span>\n              </AnimatePresence>\n            </Combobox.Chips>\n            <div className=\"flex shrink-0 items-center self-start\">\n              {selected.length > 0 ? (\n                <Combobox.Clear aria-label=\"Clear all\" className={iconButton}>\n                  <RemoveIcon />\n                </Combobox.Clear>\n              ) : null}\n              <Combobox.Trigger aria-label=\"Show options\" className={iconButton}>\n                <ChevronIcon />\n              </Combobox.Trigger>\n            </div>\n          </Combobox.InputGroup>\n          {message ? (\n            <p id={messageId} className={invalid ? \"text-sm text-red-600 dark:text-red-400\" : \"text-sm text-zinc-500 dark:text-zinc-400\"}>\n              {message}\n            </p>\n          ) : null}\n        </div>\n\n        <Combobox.Portal>\n          <Combobox.Positioner side=\"bottom\" align=\"start\" sideOffset={6} className=\"z-50 outline-hidden\">\n            <Combobox.Popup\n              className={cx(\n                \"w-(--anchor-width) max-w-(--available-width) origin-(--transform-origin) overflow-hidden rounded-xl outline-hidden\",\n                \"border border-zinc-950/10 bg-white text-zinc-950 shadow-[0_12px_32px_-8px_rgb(0_0_0/0.18)]\",\n                \"dark:border-white/15 dark:bg-black dark:text-white dark:shadow-[0_16px_48px_-12px_rgb(0_0_0/1),inset_0_1px_0_rgb(255_255_255/0.08)]\",\n                \"transition-[opacity,scale] duration-160 ease-[cubic-bezier(0.23,1,0.32,1)] motion-reduce:transition-none\",\n                \"data-[starting-style]:opacity-0 motion-safe:data-[starting-style]:scale-96\",\n                \"data-[ending-style]:opacity-0 data-[ending-style]:duration-110 data-[ending-style]:ease-out motion-safe:data-[ending-style]:scale-98\",\n              )}\n            >\n              {full ? (\n                <p className=\"border-b border-zinc-950/[0.07] px-3.5 py-2 text-xs text-zinc-500 dark:border-white/[0.08] dark:text-zinc-400\">\n                  {`You can pick up to ${max}. Remove one to choose another.`}\n                </p>\n              ) : null}\n              <Combobox.Empty className=\"px-3 py-6 text-center text-sm text-zinc-500 empty:m-0 empty:p-0 dark:text-zinc-400\">\n                {emptyMessage}\n              </Combobox.Empty>\n              <Combobox.List className=\"max-h-[min(var(--available-height),18rem)] scroll-py-1.5 overflow-y-auto overscroll-contain p-1.5 outline-hidden data-[empty]:p-0\">\n                {(item: ViewItem) => {\n                  const isSelected = values.includes(item.value);\n                  return (\n                    <Combobox.Item\n                      key={item.create ? `create:${item.value}` : item.value}\n                      value={item}\n                      disabled={item.disabled || (full && !isSelected)}\n                      className={cx(\n                        \"group/option relative flex h-8 cursor-default items-center gap-2.5 rounded-md px-2 text-sm outline-hidden select-none\",\n                        \"text-zinc-700 data-[highlighted]:bg-zinc-950/[0.05] data-[highlighted]:text-zinc-950\",\n                        \"dark:text-zinc-300 dark:data-[highlighted]:bg-white/[0.08] dark:data-[highlighted]:text-white\",\n                        \"data-[selected]:text-zinc-950 dark:data-[selected]:text-white\",\n                        \"data-[disabled]:pointer-events-none data-[disabled]:opacity-45\",\n                      )}\n                    >\n                      {item.create ? (\n                        <>\n                          <span aria-hidden=\"true\" className=\"flex size-4 shrink-0 items-center justify-center text-zinc-500\">\n                            <svg viewBox=\"0 0 16 16\" fill=\"none\" className=\"size-4\">\n                              <path d=\"M8 3.5v9M3.5 8h9\" stroke=\"currentColor\" strokeWidth=\"1.5\" strokeLinecap=\"round\" />\n                            </svg>\n                          </span>\n                          <span className=\"min-w-0 flex-1 truncate\">\n                            Add <span className=\"font-medium text-zinc-950 dark:text-white\">{`“${item.label}”`}</span>\n                          </span>\n                          <span className=\"shrink-0 text-xs text-zinc-400 dark:text-zinc-500\">Enter</span>\n                        </>\n                      ) : (\n                        <>\n                          {/* A check box that fills when the option is picked. */}\n                          <span\n                            aria-hidden=\"true\"\n                            className={cx(\n                              \"flex size-4 shrink-0 items-center justify-center rounded-[4px] border\",\n                              \"border-zinc-950/20 text-white dark:border-white/25 dark:text-black\",\n                              \"transition-[background-color,border-color] duration-150 ease-out motion-reduce:transition-none\",\n                              \"group-data-[selected]/option:border-zinc-950 group-data-[selected]/option:bg-zinc-950 dark:group-data-[selected]/option:border-white dark:group-data-[selected]/option:bg-white\",\n                            )}\n                          >\n                            <svg viewBox=\"0 0 16 16\" fill=\"none\" className=\"size-3\">\n                              <path\n                                d=\"M3.5 8.5l3 3 6-7\"\n                                stroke=\"currentColor\"\n                                strokeWidth=\"2\"\n                                strokeLinecap=\"round\"\n                                strokeLinejoin=\"round\"\n                                pathLength={1}\n                                strokeDasharray=\"1\"\n                                className=\"[stroke-dashoffset:1] transition-[stroke-dashoffset] duration-200 ease-[cubic-bezier(0.23,1,0.32,1)] group-data-[selected]/option:[stroke-dashoffset:0] motion-reduce:transition-none\"\n                              />\n                            </svg>\n                          </span>\n                          {item.icon != null ? (\n                            <span aria-hidden=\"true\" className=\"flex size-4 shrink-0 items-center justify-center text-zinc-500 [&_svg]:size-4\">\n                              {item.icon}\n                            </span>\n                          ) : null}\n                          <span className=\"min-w-0 flex-1 truncate\">{item.label}</span>\n                          {item.description ? (\n                            <span className=\"shrink-0 truncate text-xs text-zinc-400 dark:text-zinc-500\">{item.description}</span>\n                          ) : null}\n                        </>\n                      )}\n                    </Combobox.Item>\n                  );\n                }}\n              </Combobox.List>\n            </Combobox.Popup>\n          </Combobox.Positioner>\n        </Combobox.Portal>\n      </Combobox.Root>\n    </MotionConfig>\n  );\n}\n"
    }
  ],
  "example": {
    "content": "\"use client\";\n\nimport { useState } from \"react\";\nimport { MultiSelect, type MultiSelectOption } from \"@/components/shaken/ui/multi-select\";\n\nfunction Initials({ name }: { name: string }) {\n  const letters = name\n    .split(\" \")\n    .map((part) => part[0])\n    .join(\"\")\n    .slice(0, 2);\n  return (\n    <span className=\"flex size-4 items-center justify-center rounded-full bg-zinc-950/[0.08] text-[8px] font-semibold text-zinc-700 dark:bg-white/15 dark:text-zinc-200\">\n      {letters}\n    </span>\n  );\n}\n\nconst people = [\n  { name: \"Amara Okafor\", role: \"Platform\" },\n  { name: \"Jonas Lindqvist\", role: \"Billing\" },\n  { name: \"Priya Raman\", role: \"Security\" },\n  { name: \"Tomás Herrera\", role: \"Platform\" },\n  { name: \"Mei Tanaka\", role: \"Design\" },\n  { name: \"Elif Demir\", role: \"Data\" },\n  { name: \"Kwame Mensah\", role: \"Infra\" },\n];\n\nconst reviewers: MultiSelectOption[] = people.map((person) => ({\n  value: person.name.toLowerCase().replace(/\\s+/g, \"-\"),\n  label: person.name,\n  description: person.role,\n  icon: <Initials name={person.name} />,\n}));\n\nconst labels: MultiSelectOption[] = [\"bug\", \"regression\", \"needs-repro\", \"billing\", \"agent-runtime\", \"docs\", \"good first issue\"].map((label) => ({\n  value: label,\n  label,\n}));\n\nexport default function MultiSelectExample() {\n  const [selected, setSelected] = useState([\"amara-okafor\", \"priya-raman\"]);\n\n  return (\n    <div className=\"grid w-full max-w-sm gap-6\">\n      <MultiSelect\n        label=\"Reviewers\"\n        options={reviewers}\n        value={selected}\n        onValueChange={setSelected}\n        max={3}\n        placeholder=\"Add reviewers\"\n        description=\"Two approvals are required to merge.\"\n      />\n      <MultiSelect\n        label=\"Labels\"\n        options={labels}\n        defaultValue={[\"regression\", \"agent-runtime\"]}\n        creatable\n        placeholder=\"Type to add a label\"\n        description=\"Press Enter or comma to add a new label.\"\n      />\n    </div>\n  );\n}\n"
  }
}
