MultiSelect

1.2.1

Permite elegir varias opciones dentro de una lista predefinida, mostradas como chips removibles dentro del campo.

Ver en Figma

Cuándo usar

Elegir varios valores dentro de un mismo campo: seleccionar un conjunto de opciones relacionadas sin ocupar espacio permanente en la pantalla. Ej.: "Métodos de envío habilitados", "Etiquetas del producto".
Filtrar un listado por más de un criterio a la vez: aplicar varios valores de un mismo eje de filtro sin necesitar un control por valor. Ej.: filtrar pedidos por más de un estado o por más de una sucursal.
Reducir el espacio de una lista larga de opciones múltiples: cuando existen muchas alternativas y mostrarlas todas como Checkbox recargaría la pantalla.

Cuándo no usar

Elegir una única opción dentro de una lista: el MultiSelect está pensado para más de un valor a la vez. En su lugar, usar Select.
Elegir una opción entre pocas alternativas visibles: con menos de 4 opciones, mostrarlas todas mejora la comparación directa. En su lugar, usar Checkbox.
Ingresar texto libre que no corresponde a una lista predefinida: cuando el valor no pertenece a un conjunto cerrado de opciones. En su lugar, usar Input.

Anatomía

Seleccioná métodos de envío

Opciones seleccionadas

Container: campo interactivo que recibe el foco y despliega la lista de opciones al hacer clic.
Chip: opción seleccionada, mostrada como un chip removible dentro del campo; al hacer clic en su ícono de cierre, la opción vuelve a estar disponible en la lista.
Icon: ícono ChevronDownIcon que indica que el campo despliega una lista de opciones.

Al abrir el campo se despliega, mediante un Popover, la lista de opciones todavía no seleccionadas. Cuando no hay ninguna opción elegida, el Container muestra el texto de placeholder en lugar de los chips.

Variantes

Apariencia

Neutral: apariencia por defecto, para un campo de formulario sin ninguna validación puntual. Ej.: "Etiquetas del producto".

Danger: señala un error de validación en la selección. Ej.: un campo obligatorio que quedó sin completar al enviar el formulario.

Warning: advierte una condición que conviene revisar, sin bloquear el envío del formulario. Ej.: una combinación de opciones que puede afectar otra configuración ya definida.

Success: confirma que la selección es válida. Ej.: una configuración obligatoria que ya quedó completa.

Aplicación

Suele aparecer en formularios de configuración y filtros de listados, acompañado siempre de un Label que identifica el dato solicitado.

Métodos de envío

Seleccioná los métodos habilitados

Do and Don'ts

Etiquetas

Seleccioná etiquetas

Redactar cada opción de forma breve y específica, para identificar su significado de un vistazo.

Etiquetas

Seleccioná etiquetas

Evitar opciones genéricas o ambiguas que obliguen a adivinar qué representan.

Sucursales

Seleccioná sucursales

Usar el MultiSelect cuando la persona puede elegir más de un valor a la vez.

Moneda de la tienda

Seleccioná una moneda

No usar el MultiSelect para elegir un único valor excluyente: agrega chips innecesarios.

Accesibilidad

Etiqueta asociada: acompañar siempre el campo con un Label vinculado por id, para que los lectores de pantalla anuncien qué dato se solicita.
Foco visible: el campo muestra un anillo de foco (:focus-visible) al navegarlo con teclado.
No depender solo del color: las apariencias danger, warning y success deben acompañarse de un texto de ayuda o error, ya que el color del borde por sí solo no comunica el estado a personas con baja visión.
Chip removible con acción clara: cada opción seleccionada se quita haciendo clic en su ícono de cierre, sin necesitar abrir la lista de opciones para deseleccionar.

Implementación

Instalá el componente vía terminal.

npm install @nimbus-ds/components

Default

With preselected values

Danger

Skeleton

import React, { useState } from "react";
import { MultiSelect } from "@nimbus-ds/components";
import { mockShippingMethodOptions as options } from "lib/mocks/mock-multi-select-options";

const Example: React.FC = () => {
  const [value, setValue] = useState<typeof options>([]);
  return (
    <MultiSelect
      id="multi-select-default"
      name="multi-select-default"
      placeholder="Seleccioná métodos de envío"
      options={options}
      value={value}
      onChange={(event: any) => setValue(event)}
    />
  );
};
export default Example;

Props

Las propiedades adicionales se pasan al elemento contenedor del campo.

Componentes relacionados

Select — Para elegir una única opción dentro de una lista predefinida.
Checkbox — Para seleccionar una o varias opciones de forma independiente entre sí, con todas las alternativas visibles.
Chip — Componente que representa cada opción seleccionada dentro del campo.
Input — Para ingresar texto libre en lugar de elegir entre opciones predefinidas.
Label — Para identificar el dato que el campo solicita.

MultiSelect

Name	Type	Default	Description
name*	string		The name of the wrapper element or the select element when native.
id*	string		The id of the wrapper element or the select element when native.
appearance	'danger' 'neutral' 'success' 'warning'	'neutral'	Change the visual style of the select.
options*	array		Options of the MultiSelect
onChange	object		Options of the MultiSelect
value	array		Deafult of the MultiSelect
zIndex	'100' '1000' '1100' '200' '300' '400' '500' '600' '700' '800' '900'		ZIndex of the MultiSelect

MultiSelect.Skeleton

Name	Type	Description
width	string	Width of the skeleton. Useful when the skeleton is inside an inline element with no width of its own.
className	string
data-testid	string	This is an attribute used to identify a DOM node for testing purposes.

Ayudanos a mejorar la documentación

¿Encontraste un problema o tenés una sugerencia? Contanos.

Compartí tu opinión