MultiSelect

1.2.1

Permite escolher várias opções dentro de uma lista predefinida, exibidas como chips removíveis dentro do campo.

Ver no Figma

Quando usar

Escolher vários valores dentro de um mesmo campo: selecionar um conjunto de opções relacionadas sem ocupar espaço permanente na tela. Ex.: "Métodos de envio habilitados", "Tags do produto".
Filtrar uma listagem por mais de um critério ao mesmo tempo: aplicar vários valores de um mesmo eixo de filtro sem precisar de um controle por valor. Ex.: filtrar pedidos por mais de um status ou por mais de uma filial.
Reduzir o espaço de uma lista longa de opções múltiplas: quando existem muitas alternativas e mostrá-las todas como Checkbox sobrecarregaria a tela.

Quando não usar

Escolher uma única opção dentro de uma lista: o MultiSelect é pensado para mais de um valor por vez. Usar Select em vez disso.
Escolher uma opção entre poucas alternativas visíveis: com menos de 4 opções, mostrá-las todas melhora a comparação direta. Usar Checkbox em vez disso.
Inserir texto livre que não corresponde a uma lista predefinida: quando o valor não pertence a um conjunto fechado de opções. Usar Input em vez disso.

Anatomia

Selecione métodos de envio

Opções selecionadas

Container: campo interativo que recebe o foco e exibe a lista de opções ao ser clicado.
Chip: opção selecionada, exibida como um chip removível dentro do campo; ao clicar no seu ícone de fechar, a opção volta a ficar disponível na lista.
Icon: ícone ChevronDownIcon que indica que o campo exibe uma lista de opções.

Ao abrir o campo, é exibida, por meio de um Popover, a lista de opções ainda não selecionadas. Quando nenhuma opção está selecionada, o Container mostra o texto de placeholder no lugar dos chips.

Variantes

Aparência

Neutral: aparência padrão, para um campo de formulário sem nenhuma validação específica. Ex.: "Tags do produto".

Danger: sinaliza um erro de validação na seleção. Ex.: um campo obrigatório que ficou sem preencher ao enviar o formulário.

Warning: alerta sobre uma condição que vale revisar, sem bloquear o envio do formulário. Ex.: uma combinação de opções que pode afetar outra configuração já definida.

Success: confirma que a seleção é válida. Ex.: uma configuração obrigatória que já ficou completa.

Aplicação

Costuma aparecer em formulários de configuração e filtros de listagens, sempre acompanhado de um Label que identifica o dado solicitado.

Métodos de envio

Selecione os métodos habilitados

Do and Don'ts

Acessibilidade

Etiqueta associada: acompanhar sempre o campo com um Label vinculado por id, para que os leitores de tela anunciem qual dado está sendo solicitado.
Foco visível: o campo mostra um anel de foco (:focus-visible) ao navegar por teclado.
Não depender só da cor: as aparências danger, warning e success devem ser acompanhadas de um texto de ajuda ou erro, já que a cor da borda por si só não comunica o estado para pessoas com baixa visão.
Chip removível com ação clara: cada opção selecionada é removida ao clicar no seu ícone de fechar, sem precisar abrir a lista de opções para desmarcar.

Implementação

Instale o componente via 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

As propriedades adicionais são passadas para o elemento container do campo.

Componentes relacionados

Select — Para escolher uma única opção dentro de uma lista predefinida.
Checkbox — Para selecionar uma ou várias opções de forma independente entre si, com todas as alternativas visíveis.
Chip — Componente que representa cada opção selecionada dentro do campo.
Input — Para inserir texto livre em vez de escolher entre opções predefinidas.
Label — Para identificar o dado que o 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.

Ajude-nos a melhorar a documentação

Encontrou um problema ou tem uma sugestão? Conte para a gente.

Compartilhe seu feedback