Todos los componentes (204)

Selector múltiple

Elección · MultiSelect · .amset-multiple

Qué es y cuándo usarlo

Elegir varios valores de una lista: las categorías de un producto, los destinatarios de un aviso, unas etiquetas. Lo elegido queda a la vista en fichas que se quitan con el ratón o con el teclado, y el campo filtra la lista mientras se escribe.

Cuándo usarlo

Varias opciones de una lista demasiado larga para enseñarla entera.
max limita cuántas se eligen y cuenta «2 de 4» debajo del campo.
allowsCreate para etiquetas libres: lo escrito aparece al final de la lista como una opción más, Añadir «broches», que funciona igual con teclado, ratón o dedo.
serverFiltered cuando la lista llega ya filtrada de una búsqueda; onType avisa de cada letra, y loading marca el campo como ocupado mientras llegan las opciones.
size y variant son los de todos los campos (la caja mide 30, 36 o 44 px y las fichas crecen con ella). readOnly enseña lo elegido sin botones de quitar; disabled lo apaga todo y lo saca del orden del Tab.

Cuándo no

Una sola opción: Select, o SearchField si hay que buscar.
Pocas opciones que conviene ver a la vez: Checkbox o SelectableList con selection="multiple".
Repartir un catálogo viendo también lo que queda fuera: TransferList.

Teclado: en el campo, escribir filtra sin distinguir tildes ni mayúsculas; la flecha abajo abre la lista y las flechas marcan una opción sin sacar el foco del campo; Intro añade la marcada y el campo se vacía para seguir añadiendo; Escape cierra la lista. Retroceso con el campo vacío quita la última ficha. Las fichas son una rejilla que se recorre con las flechas: Supr o Retroceso quitan la que tiene el foco y el foco pasa a la siguiente, en vez de perderse. En solo lectura la rejilla se recorre pero no se quita nada; deshabilitado, ni las fichas ni el campo reciben el foco.

Accesibilidad: sin nada elegido, el campo se llama como la etiqueta. Con fichas, la etiqueta nombra la rejilla de fichas y el campo pasa a llamarse «Añadir a Categorías». Cada ficha tiene su botón de quitar con nombre, que se oye una sola vez: «Quitar Anillos», o exactamente lo que diga removeText. La ayuda, la cuenta y el error se leen como descripción del campo. Con el máximo alcanzado, la lista dice «Ya has elegido 4, que es el máximo» en vez de quedarse vacía. El foco de la caja es el anillo de 2 px de los campos, y el de cada ficha, el de los botones. Con el dedo, fichas y botones de quitar miden 44 px.

Movimiento: la ficha que se añade entra creciendo un poco; el borde de la ficha y el fondo del botón de quitar cambian con una transición corta, y el botón cede al pulsarlo.

Aspecto fino: la caja comparte las variables de los campos, --amset-field-*. Las fichas, --amset-multiple-chip-height (22, 26 o 32 px según size), --amset-multiple-chip-font, --amset-multiple-chip-radius, --amset-multiple-chip-background y --amset-multiple-chip-ink; el botón de quitar, --amset-multiple-remove (su lado). La lista se ajusta con amset-multiple__panel.

Cómo se ve

Etiquetas

Urgente

<MultiSelect
  label="Etiquetas"
  options={[
    { key: 'urgente', label: 'Urgente' },
    { key: 'cliente', label: 'Cliente nuevo' },
  ]}
  initialValue={['urgente']}
/>

Props

Se importa con import { MultiSelect } from '@amset/ui'. Las obligatorias van marcadas.

Prop	Tipo	Para qué sirve
`label`obligatoria	`string`	—
`options`obligatoria	`readonly ListOption[]`	—
`allowsCreate`	`boolean`	Permite crear valores que no estan en la lista (etiquetas libres).
`className`	`string`	Se une a las clases de la biblioteca, no las sustituye.
`disabled`	`boolean`	Ni se escribe, ni se abre la lista, ni se quitan fichas: todo sale del orden del Tab.
`error`	`string`	—
`hint`	`string`	—
`initialValue`	`readonly string[]`	—
`invalid`	`boolean`	Marca el campo como no valido. Lo normal es pasar `error`, que ademas lo explica.
`loading`	`boolean`	Las opciones estan llegando. Marca el campo como ocupado, enseña un anillo y una fila `loadingText` en la lista; las opciones que ya hubiera se quedan.
`loadingText`	`string`	Lo que dice la fila de carga. Por defecto, «Cargando…».
`max`	`number`	Cuantas se pueden elegir como mucho.
`noResultsMessage`	`string`	—
`offset`	`number`	—
`onChange`	`(keys: readonly string[]) => void`	—
`onType`	`(text: string) => void`	—
`placeholder`	`string`	—
`placement`	`Placement`	—
`readOnly`	`boolean`	Lo elegido se ve y el campo se enfoca, pero no se añade ni se quita nada: las fichas pierden su boton de quitar.
`removeText`	`(label: string) => string`	El nombre entero del boton de quitar cada ficha: «Quitar Anillos» por defecto. Es todo el nombre; no se le pega nada detras.
`renderOption`	`OptionRender<ListOption>`	Pinta el interior de cada opcion de la lista: un avatar, dos lineas, un precio. El nombre que lee el lector de pantalla sigue siendo `label`.
`renderTag`	`(option: ListOption) => ReactNode`	Pinta cada ficha de lo elegido: un avatar con el nombre, un color. La ficha sigue llamandose `label` para el lector de pantalla y su aspa sigue ahi; esto es solo lo que se ve dentro.
`required`	`boolean`	—
`serverFiltered`	`boolean`	La lista ya llega filtrada de fuera (busqueda en el servidor).
`size`	`"sm" \| "md" \| "lg"`	—
`value`	`readonly string[]`	Claves elegidas. Si se pasa, el estado lo lleva quien use el componente.
`variant`	`FieldVariant`	—

Acepta además los atributos del elemento que pinta: className, style, data-*, aria-* y sus eventos.

Mandos

Estas variables CSS son la forma de adaptarlo. Se declaran sobre el selector del componente, no en :root: la hoja las redeclara en la propia regla y una declaración en el mismo elemento gana siempre.

Variable	Por defecto
`--amset-multiple-chip-height`	`1.625rem`
`--amset-multiple-chip-font`	`var(--amset-text-sm)`
`--amset-multiple-chip-radius`	`var(--amset-radius)`
`--amset-multiple-chip-background`	`var(--amset-accent-soft)`
`--amset-multiple-chip-ink`	`var(--amset-accent-text)`
`--amset-multiple-remove`	`1.25rem`

Cómo se cambia

.amset-multiple {
  --amset-multiple-chip-height: ...;
  --amset-multiple-chip-font: ...;
}

En el banco de pruebas

Cada estado y cada variante, para tocarlos de uno en uno, en su ficha de ui.amset.tech: