# MultiSelect (/docs/multi-select)
`MultiSelect` lets the user pick several values, rendered as removable [`Pill`](/docs/pill)s in a wrapping [`PillsInput`](/docs/pills-input)-style field, searchable by default. It's the whole family in one component: the [`Combobox`](/docs/combobox) engine (in `multiple` mode) drives selection, the control is the pills shell, and each value is a `Pill`.
```tsx
import { MultiSelect } from '@42-central/ui-react/multi-select';
```
## Playground [#playground]
## Adding & removing [#adding--removing]
Type to filter, pick to add — a check marks selected options. Remove a value with its pill's **×**, **Backspace** on the empty field, or the **clear** button (`clearable`). `data` accepts the same shapes as [`Select`](/docs/select), including groups.
## Hide picked options [#hide-picked-options]
With `hidePickedOptions`, chosen values drop out of the dropdown so the list only ever shows what's still addable.
## Max values [#max-values]
`maxValues` caps the selection — once reached, adding more is rejected (removals still work).
## Not searchable [#not-searchable]
`searchable={false}` turns it into a click-to-open multi-picker — the field no longer filters, it just toggles the dropdown.
## Max lines [#max-lines]
`maxLines` caps the pills at N rows; any beyond collapse into a static **+N** counter (it's measured, so it adapts to the field's width). The hidden values stay selected and submitted — deselect them from the dropdown.
## Start & end slots [#start--end-slots]
`startSlot` and `endSlot` place content at the field's inline-start / inline-end with the same slot layout as [`Input`](/docs/input). `endSlot` renders before the built-in clear button and chevron.
## Colored options [#colored-options]
Give a `data` item a `color` and its pill picks up that palette once selected — the same [`Color`](/docs/pill) accent `Pill` and `Badge` already use.
```tsx
const statuses = [
{ value: 'todo', label: 'To do', color: 'neutral' },
{ value: 'in-progress', label: 'In progress', color: 'blue' },
{ value: 'done', label: 'Done', color: 'green' },
];
```
## Custom rendering [#custom-rendering]
`renderItem` owns each dropdown option's content — the same `(item, state) => ReactNode` renderer as [`Select`](/docs/select#custom-rendering), with `item` being `{ value, label, disabled }` and state `{ selected, highlighted }`. The pills in the field still render from the label; only the dropdown rows change. Define the function in a `"use client"` module so it survives the server → client boundary.
### Typed payload [#typed-payload]
Attach arbitrary data to an item via `payload` and read it back as `item.payload` in `renderItem` — inferred from `data`, and `undefined` for bare-string or payload-less items. Only the dropdown rows see it; the pills still render the label.
```tsx
'use client';
import { Badge } from '@42-central/ui-react/badge';
const projects = [
{ value: 'libft', label: 'Libft', payload: { xp: 420 } },
{ value: 'webserv', label: 'Webserv', payload: { xp: 1340 } },
];
// item.payload is inferred as { xp: number } | undefined
const renderOption = (item) => (
{item.label}
{item.payload && {item.payload.xp} XP}
);
```
## Controlled [#controlled]
`value` is a `string[]`; `onChange` hands you the full selection on every add or remove.
```tsx
'use client';
import { useState } from 'react';
import { MultiSelect } from '@42-central/ui-react/multi-select';
export function ProjectPicker() {
const [value, setValue] = useState([]);
return (
);
}
```
## Label, description & error [#label-description--error]
Built-in via [`Field`](/docs/field), like the rest of the family:
## API [#api]
## Accessibility [#accessibility]
* Full combobox keyboard model from Ark: type to filter, `↑` / `↓` to move, `Enter` to toggle an option, `Backspace` on the empty field to remove the last value, `Esc` to close.
* Each pill's × is an independently focusable, labelled button; `role="combobox"` / `listbox` / `option` and the active-descendant wiring come from the Ark machine, with label / description / error associated via the built-in `Field`.
* RTL: the pills, field, and dropdown all mirror under `dir="rtl"`.