Stepwise UI

Multiselect

Multi-option selector with removable pills in the trigger for selected values. Opens into a floating panel - matching Select and Combobox - with checkable rows. Supports overflow with a +N badge when selections exceed maxVisible.

Installation

npx stepwise-ui add multiselect

Default

import { Multiselect } from '@/components/stepwise/multiselect'

const options = [
  { value: 'vanilla',   label: 'Vanilla' },
  { value: 'chocolate', label: 'Chocolate' },
  { value: 'pistachio', label: 'Pistachio' },
]

<Multiselect options={options} placeholder="Choose flavors" />

With label

<Multiselect
  label="Ice cream flavors"
  options={options}
  placeholder="Pick your favorites"
/>
<Multiselect
  label="Skills"
  options={skills}
  placeholder="Select skills"
/>

Controlled

Pass value (string array) and onChange for controlled usage. The component manages state internally when uncontrolled.

Selected: react, typescript

const [values, setValues] = useState<string[]>(['react', 'typescript'])

<Multiselect
  label="Skills"
  options={skills}
  value={values}
  onChange={setValues}
/>

Overflow

When more items are selected than maxVisible (default: 2), the remaining count shows as a +N chip. Click the trigger to see all options.
// maxVisible controls how many chips show before "+N"
<Multiselect
  options={options}
  value={['vanilla', 'chocolate', 'strawberry', 'pistachio']}
  onChange={setValues}
  maxVisible={2}
/>

Props

PropTypeDescription
options
MultiselectOption[]
Array of { value, label } objects.
value
string[]
Controlled selected values.
onChange
(values: string[]) => void
Called when selection changes.
placeholder
string
Text shown when nothing is selected.
label
string
Label rendered above the trigger.
maxVisible
number
Max pills shown before +N. Default: 2.
disabled
boolean
Disables the trigger.