# MultiSelect

> Elegir varias opciones de una lista: los elegidos como chips en el campo y la lista del menú de iCloud con el círculo de acento a la derecha, con «Seleccionar todo» y tope.

```tsx
import { MultiSelect } from "sebs7n-ui/multi-select"
```

## Ejemplos

### Medios de pago

Los elegidos como chips y la lista del menú con el círculo de acento a la derecha. Se escribe para filtrar (sin tildes), Enter elige y la lista queda abierta; «Seleccionar todo» marca las que se ven.

```tsx
import { Field, FieldDescription, FieldLabel } from "sebs7n-ui"
import { MultiSelect } from "sebs7n-ui/multi-select"
import { useState } from "react"

function Basico() {
  const [medios, setMedios] = useState(["transferencia", "tarjeta"])
  return (
    <Field className="w-full max-w-sm">
      <FieldLabel htmlFor="medios">Medios de pago aceptados</FieldLabel>
      <MultiSelect id="medios" onValueChange={setMedios} options={MEDIOS} placeholder="Elegí uno o más" selectAll value={medios} />
      <FieldDescription>Se muestran en el link de pago de cada factura.</FieldDescription>
    </Field>
  )
}
```

### Con tope

`max` apaga el resto al llegar y la lista lo dice.

```tsx
import { Field, FieldLabel } from "sebs7n-ui"
import { MultiSelect } from "sebs7n-ui/multi-select"

function ConTope() {
  return (
    <Field className="w-full max-w-sm">
      <FieldLabel htmlFor="destacados">Clientes destacados (hasta 3)</FieldLabel>
      <MultiSelect defaultValue={["acme-s-a-"]} id="destacados" max={3} options={CLIENTES} placeholder="Buscar clientes" />
    </Field>
  )
}
```

## Props

### MultiSelect

| Prop | Tipo | Por defecto | Descripción |
|---|---|---|---|
| `options` * | `MultiSelectOption[]` | — | Las opciones: `value`, `label` y `disabled`. |
| `aria-label` | `string` | — | Nombre accesible del elemento. |
| `aria-labelledby` | `string` | — | El `id` del elemento que nombra el campo, si no es un `<label>`. |
| `defaultValue` | `string[]` | `[]` | Los elegidos al arrancar. |
| `disabled` | `boolean` | — | Apaga el campo. |
| `id` | `string` | — | El `id` del campo, para un `<Label htmlFor>`. |
| `labels` | `Partial<Labels["multiSelect"]>` | — | Textos: `selectAll` y `max`. «Limpiar», «Quitar» y «Sin resultados» son los de `combobox`. |
| `max` | `number` | — | Cuántas se pueden elegir. |
| `name` | `string` | — | El nombre en un `<form>`: se envía un valor por elegido. |
| `onValueChange` | `(value: string[]) => void` | — | Se llama con los valores elegidos, en el orden de `options`. |
| `placeholder` | `string` | — | Lo que dice el campo sin elegidos. |
| `selectAll` | `boolean` | `false` | Una opción «Seleccionar todo» arriba de la lista. |
| `showClear` | `boolean` | `true` | El botón que vacía la selección. Por defecto, sí. |
| `size` | `"sm" \| "md" \| "lg"` | `"md"` | `sm` 28, `md` 36 (default), `lg` 40. |
| `value` | `string[]` | — | Los valores elegidos. Pasarlo lo vuelve controlado. |
| `className` | `string` | — | Clases de la superficie. |

`*` obligatoria.

## Teclado

| Tecla | Qué hace |
|---|---|
| ↓ / ↑ | Abren la lista y recorren las opciones. |
| a–z | Filtran la lista, sin tildes ni mayúsculas. |
| Enter | Elige o quita la opción resaltada; la lista queda abierta para seguir. |
| Backspace | Con el campo vacío, quita el último elegido. |
| ← / → | Con el campo vacío, recorren los chips; Backspace o Delete quitan el enfocado. |
| Escape | Cierra la lista; otra vez, vacía la búsqueda. |

## Accesibilidad

- Es un `combobox` con `listbox` de `Combobox` (Base UI): **nombre obligatorio** con `aria-label`, `aria-labelledby` o un `<Label htmlFor>` al `id`.
- Cada opción elegida lleva `aria-selected="true"`; el círculo de acento es decorativo.
- Cada chip tiene su botón «Quitar Tarjeta de crédito», con el nombre de la opción.
- «Seleccionar todo» es una opción más, primera, que queda `aria-selected` cuando todas las que se ven están elegidas.
- Con `max`, las demás quedan `aria-disabled` y la lista dice «Máximo 3» en su región viva.

## Reglas de uso

- **Para elegir varias de una lista de más de 6 opciones o que se busca.** Con pocas opciones fijas, `CheckboxGroup` las muestra todas sin abrir nada.
- Para una sola, `Combobox` o `Select`.
- `value` sale en el orden de `options`, no en el de los clicks, y los chips también.
- «Seleccionar todo» marca las habilitadas **que se ven**: con una búsqueda, las que coinciden. No aparece si `max` es menor que esas opciones.
- Solo por subpath (`sebs7n-ui/multi-select`): no está en el barrel, por peso.

## Relacionados

[combobox](/docs/components/combobox.md) · [checkbox-group](/docs/components/checkbox-group.md) · [select](/docs/components/select.md)