MultiSelect

A dropdown that picks several values and shows them as chips with a rolling "+N" overflow count.

When to use

• Choosing several values from a known list: checks, languages, labels, permissions.
• When the field must stay one line tall; maxVisible chips show and the rest collapse into a count.
• For free-form values use TagInput; for one value use Select or Combobox; for a few visible toggles use Checkbox rows.

Usage

import { MultiSelect } from "@/components/iris/multi-select/multi-select";
function SessionChecks() {
  const [value, setValue] = React.useState(["email", "phone"]);
  return h(MultiSelect, {
    label: "Session checks",
    options: [
      { value: "email", label: "Email" },
      { value: "phone", label: "Phone" },
      { value: "identity", label: "Identity" },
      { value: "property", label: "Property link (rentals only)", disabled: true },
    ],
    value,
    onValueChange: setValue,
  });
}

Props

Prop	Type	Default	Description
label	string	required	Visible label; also names the listbox.
options	{ value: string; label: string; disabled?: boolean }[]	required	The choices.
value / defaultValue	string[]	– / []	Controlled or initial selection.
onValueChange	(value: string[]) => void	–	Called with the full new selection.
placeholder	string	"Select options"	Shown when nothing is selected.
description	string	–	Helper copy under the field.
maxVisible	number	2	Chips shown before the "+N" count.
disabled	boolean	false	Disables the trigger and hides the clear button.
className	string	–	Extra class on the root.

Notes

• The trigger is a button with aria-haspopup="listbox"; Enter/Space open and toggle, ArrowUp/Down move the highlight, Escape closes. Options use role="option" and aria-selected.
• A clear button appears when anything is selected. A pointer down outside closes the menu. There is no open prop.
• The menu renders inline, absolutely positioned under the trigger, so leave room below it.
• Reads --surface, --hover, --line, --line-strong, --line-soft, --shadow-floating, --radius-panel, --radius-button.