Select

2.7.1

Permite escolher uma opção dentro de uma lista predefinida, exibida em um campo suspenso nativo.

Ver no Figma

Quando usar

Escolher uma configuração entre várias opções predefinidas: definir um único valor dentro de um conjunto fechado de alternativas. Ex.: "Moeda da loja", "País principal", "Idioma da loja".
Ordenar ou filtrar uma listagem: aplicar um critério sobre uma lista de dados sem ocupar espaço permanente na tela. Ex.: "Ordenar por", "Método de envio".
Reduzir o espaço de uma lista longa de opções: quando existem 4 ou mais alternativas e mostrar todas ao mesmo tempo (como em um Radio) sobrecarregaria a tela. Ex.: lista de estados, lista de métodos de pagamento.
Agrupar opções por categoria: dividir uma lista extensa em grupos com Select.Group, para facilitar localizar uma opção específica. Ex.: métodos de envio agrupados por transportadora.

Quando não usar

Escolher uma opção entre poucas alternativas visíveis: com menos de 4 opções, mostrar todas melhora a comparação direta e evita um clique adicional para abrir a lista. Nesse caso, usar Radio.
Selecionar mais de um valor ao mesmo tempo: o Select nativo admite apenas uma opção marcada. Nesse caso, usar Checkbox ou o componente MultiSelect.
Aplicar uma mudança imediata do tipo ligado/desligado: ativar ou desativar uma configuração binária com efeito imediato. Nesse caso, usar Toggle.
Mostrar um valor sem alternativas reais para escolher: se existe apenas uma opção possível (por exemplo, um único país habilitado), um Select desabilitado não representa nenhuma decisão. Nesse caso, mostrar o valor como texto simples.

Anatomia

Opções padrão

Opções agrupadas com Select.Group

Field: contêiner interativo que recebe o foco e a interação de teclado.
Placeholder option: texto da opção escolhida; quando não há seleção, exibe a opção de placeholder.
Icon: ícone ChevronDownIcon que indica que o campo exibe uma lista de opções.

Ao abrir o campo, exibe-se a lista de opções (componente Select.Option), que pode ser dividida em categorias com Select.Group (opcional) quando há muitos itens. Essa lista é o dropdown nativo do navegador: sua aparência depende do SO/navegador e o Nimbus não a estiliza.

Variantes

Aparência

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

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

Warning: alerta sobre uma condição que convém revisar, sem bloquear o envio do formulário. Ex.: uma opção que pode afetar outra configuração já definida.

Success: confirma que o valor escolhido é válido. Ex.: uma configuração obrigatória que já ficou completa.

Ai-generative: aplica uma borda com degradê de IA de forma permanente, para um campo que faz parte de uma experiência ou fluxo de inteligência artificial. Ex.: um Select dentro de um assistente de IA ou de uma função gerada com Lumi.

Gerado por IA

aiGenerated: aplica um anel de foco com degradê de IA sobre o campo para sinalizar que o valor exibido foi sugerido por inteligência artificial; tem prioridade visual sobre appearance. Ex.: uma opção pré-preenchida por uma sugestão automática que a pessoa usuária pode revisar ou alterar.

Estados

Aplicação

Costuma aparecer em formulários de configuração, filtros de listagens e modais, sempre acompanhado de um Label (direto ou por meio de FormField.Select) que identifica o dado solicitado.

Moeda

Do and Don'ts

Ordenar por

Redigir cada opção de forma breve e específica, para identificar seu significado rapidamente.

Ordenar por

Evitar opções genéricas ou ambíguas que obriguem a adivinhar o que representam.

Redigir o texto de cada opção breve e claro.

Não sobrecarregar as opções com textos longos que não conseguem ser lidos por completo.

País

Argentina

Mostrar o valor como texto simples quando existe apenas uma alternativa possível.

País

Não usar um Select desabilitado para mostrar um único valor sem alternativas reais.

Acessibilidade

Etiqueta associada: acompanhar sempre o campo com um Label (direto ou por meio de FormField.Select) vinculado pelo id, para que os leitores de tela anunciem qual dado está sendo solicitado.
Navegação por teclado: por ser um <select> nativo, é alcançável com Tab e é aberto e percorrido com as setas do teclado, sem precisar de suporte adicional.
Foco visível: o campo exibe um anel de foco (:focus-visible) ao ser navegado com teclado.
Não depender só da cor: as aparências danger, warning e success devem ser acompanhadas de um texto de ajuda ou erro (por exemplo, com FormField.Select e seu helpText), já que a cor da borda por si só não comunica o estado a pessoas com baixa visão.
Estado desabilitado: o atributo disabled bloqueia a interação e os leitores de tela o anunciam como não disponível.

Guia de conteúdo

A placeholder orienta a escolher sem adiantar uma resposta correta. Cada opção nomeia a escolha com um substantivo ou frase nominal, nunca com um verbo.

Capitalização: sentence case para as opções e para o label do Select.Group.

Pontuação: sem ponto final na placeholder option nem nas opções.

Tamanho das opções: sem quebra em várias linhas — se uma opção não couber em uma linha, reescrevê-la.

Forma verbal das opções: substantivo ou frase nominal, por exemplo "Argentina" ou "Cartão de crédito"; nunca um verbo como "Selecionar Argentina".

Ordem das opções: alfabética quando não há outro critério lógico; por frequência de uso quando existe uma distribuição clara, por exemplo os meios de pagamento mais usados primeiro.

Opção padrão: pré-selecionar a opção lógica para a maioria das pessoas usuárias quando existir; se não houver, usar a placeholder option — nunca deixar o campo vazio sem texto.

Partes

Parte	Regra de conteúdo	Exemplo
Placeholder option	"Selecione + [objeto]"	"Selecione um país"
Opção	Substantivo ou frase nominal. Sentence case. Sem ponto final. Sem quebra.	"Argentina"
Select.Group label	Substantivo breve. Sentence case.	"América do Sul"

Casos críticos

Caso	O que fazer
Select sem opção pré-selecionada	Adicionar sempre uma placeholder option — nunca deixar o campo vazio sem guia.
Opções muito longas que quebram linha	Reescrever as opções; se não for possível, revisar se Select é o componente correto.
Mais de ~10 opções sem grupos	Considerar Select.Group para organizar; se a lista for muito longa e precisar de busca, usar outro componente.
Opções em title case	Converter para sentence case; só os nomes próprios levam maiúscula.

Implementação

Instale o componente via terminal.

npm install @nimbus-ds/components

import React from "react";
import { Select } from "@nimbus-ds/components";

const Example: React.FC = () => (
  <Select appearance="neutral" id="Id" name="Name">
    <Select.Option label="This option is selected" selected value="Option 1" />
    <Select.Option disabled label="This option is disabled" value="Option 2" />
    <Select.Option label="Option 3" value="Option 3" />
    <Select.Option label="Option 4" value="Option 4" />
    <Select.Option label="Option 5" value="Option 5" />
    <Select.Option label="Option 6" value="Option 6" />
  </Select>
);

export default Example;

Props

As propriedades adicionais são passadas para o elemento <select>. Consulte a documentação do elemento select para ver a lista de atributos aceitos.

Componentes relacionados

Radio — Para escolher uma única opção entre poucas alternativas visíveis.
Checkbox — Para selecionar uma ou várias opções de forma independente entre si.
Toggle — Para ativar ou desativar uma configuração com efeito imediato.
Input — Para inserir texto livre em vez de escolher entre opções predefinidas.
Label — Para identificar o dado que o campo solicita.

Select

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.
children*	React.ReactNode		The content of the select.
appearance	'ai-generative' 'danger' 'neutral' 'success' 'warning'	'neutral'	Change the visual style of the select.
aiGenerated	boolean	'false'	Shows ai-generative appearance with active ai focus shadow. When true, this styling takes precedence over `appearance`.

Select.Group

Name	Type	Default	Description
label*	string		Label for the option group.
children*	React.ReactNode		The content of the option group.

Select.Option

Name	Type	Default	Description
label*	string		Label for the option.
value*	string		Value of the option

Select.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