Multi Select List
Explore interactive examples and all component variations in our Storybook.
The MultiSelectList component provides a scrollable, checkable list with built-in multi-selection support. It supports Shift+click for range selection, a select-all toggle, and fully customizable item rendering and labels. The generic type parameter T adapts it to any data shape.
Basic Usage
0 of 5 selected· Shift+click to select a range
Custom Item Rendering
Use renderItem to display richer content per row — icons, badges, secondary text, or any React node.
0 of 5 selected· Shift+click to select a range
Rich Item Rendering
Combine Avatar, Badge, and multi-line text to build user-card-style rows. The status dot is positioned as an overlay on the avatar using relative/absolute positioning.
0 of 6 selected· Shift+click to select a range
Custom Labels
All text in the component is overridable via the labels prop. This makes it straightforward to localise or reword any string.
0 de 3 selecionados· Shift+clique para selecionar um intervalo
Card Integration
A common pattern is embedding the list inside a Card alongside a submit action that consumes the current selection.
Properties
MultiSelectList<T>
| Property | Type | Required | Description |
|---|---|---|---|
items | T[] | ✓ | Array of items to display. |
selectedIds | string[] | ✓ | IDs of currently selected items. |
onChange | (selectedIds: string[]) => void | ✓ | Called whenever the selection changes. |
getItemId | (item: T) => string | ✓ | Extracts a unique string ID from each item. |
renderItem | (item: T) => ReactNode | ✓ | Renders the content of each row. |
labels | MultiSelectListLabels | — | Overrides for any display text. |
className | string | — | Additional CSS classes for the root element. |
MultiSelectListLabels
| Property | Type | Default | Description |
|---|---|---|---|
title | string | '' | Label shown above the list. Hidden when empty. |
selectAll | string | 'Select all' | Text for the toggle button when not all items are selected. |
deselectAll | string | 'Deselect all' | Text for the toggle button when all items are selected. |
selectedCount | (selected: number, total: number) => string | 'N of M selected' | Footer count text. |
shiftClickHint | string | '· Shift+click to select a range' | Hint shown when there is more than one item. |
Interaction Model
- Click — toggles a single item.
- Shift+click — selects (or deselects) all items between the last-clicked item and the current one, matching the direction set by the anchor click.
- Select all / Deselect all — controlled by whether every item in
itemsis present inselectedIds. Resets the Shift anchor.
Accessibility
- Checkboxes are labelled via
htmlFor/idpairs derived from each item's ID. - The list uses
<ul>/<li>semantics. - The toggle button is a native
<button type="button">— safe inside forms. select-noneon the list prevents accidental text selection during Shift+click.