Componentes

Select

beta

Seleção com menu próprio, para quando é preciso controlar a aparência das opções. Custa mais que o nativo — escolha sabendo disso.

Ainda não é estável porque Rota não varrida pelo sensor. Ausência de medição não é aprovação. O contrato de maturidade explica o que cada requisito exige.

@voxmente/ui/components/ui/select

Orientação

Seleção com menu próprio, para quando é preciso controlar a aparência das opções. Custa mais que o nativo em código e em camada — escolha sabendo disso.

Quando usar

As opções precisam de mais que texto: ícone, descrição, agrupamento.
A lista é média — grande o bastante para não caber num Radio Group, pequena o bastante para o olho percorrer.
A aparência do menu precisa ser a mesma em todos os sistemas operacionais.

Quando não usar

Em formulário simples, e principalmente no celular: o Native Select ganha do Select em quase tudo, porque usa o seletor do próprio sistema.
Quando a lista é longa demais para percorrer com o olho. Aí o usuário precisa filtrar digitando, e o componente é o Combobox.
Quando são poucas opções e todas precisam ficar visíveis para comparação — Radio Group.

Playground

Tamanhosize

Texto de vazioplaceholder

Desabilitadodisabled

<Select defaultValue="leitura">
  <SelectTrigger>
    <SelectValue placeholder="Selecione uma trilha" />
  </SelectTrigger>
  <SelectContent>
    <SelectItem value="leitura">Trilha de leitura</SelectItem>
    <SelectItem value="escrita">Trilha de escrita</SelectItem>
    <SelectItem value="matematica">Trilha de matemática</SelectItem>
  </SelectContent>
</Select>

Anatomia

As partes deste componente e como se aninham. A árvore vem das demonstrações desta página, então descreve um exemplo que renderiza.

Select
  └─ SelectTrigger
    └─ SelectValue
  └─ SelectContent
    └─ SelectGroup
      └─ SelectLabel
      └─ SelectItem
    └─ SelectSeparator
    └─ SelectGroup
      └─ SelectLabel
      └─ SelectItem

Exportadas, mas sem demonstração nesta página: SelectScrollDownButton, SelectScrollUpButton.

Uso

Escolha entre poucas opções quando o rótulo importa mais que a digitação. Prefira o NativeSelect em formulário simples — leia a comparação abaixo antes de escolher.

Select ou NativeSelect?

Os dois resolvem a mesma pergunta — escolher um valor entre opções — mas não são intercambiáveis.

Use Select quando o item escolhido precisa de mais do que texto — ícone, descrição, agrupamento visual — ou quando o menu abre sobre o restante da tela, como num filtro de painel.

Use NativeSelect em formulário simples: cadastro de aluno, dados da escola, campos de uma única linha. No celular ele abre a roda nativa do sistema operacional, maior e mais rápida de tocar que qualquer popup customizado — e sai de graça, sem JavaScript de posicionamento.

Tamanhos

`size` no `SelectTrigger` controla a altura. Use `sm` em barras de filtro densas.

Grupos e rótulos

`SelectGroup` e `SelectLabel` separam opções por categoria. `SelectSeparator` marca a divisão entre grupos.

Lista rolável

Passou de uma tela de opções, o conteúdo rola sozinho — os botões de seta aparecem no topo e no rodapé só quando há mais itens para ver.

Alinhamento com o gatilho

Por padrão, `alignItemWithTrigger` faz o item selecionado abrir exatamente sobre o gatilho — como um menu de sistema operacional. Desligue quando o menu precisa cair sempre abaixo, sem sobrepor o campo.

Inválido

`aria-invalid` no `SelectTrigger` marca o erro visualmente e para o leitor de tela ao mesmo tempo — não separe as duas coisas.

Desabilitado

`disabled` no `Select` bloqueia o gatilho inteiro. Um item individual também aceita `disabled` — útil para opção temporariamente indisponível.

Acessibilidade

O que o componente já garante, e o que continua sendo responsabilidade da tela.

O gatilho precisa de rótulo: dentro de um Field, ou com nome acessível próprio.
O menu já responde a teclado — setas, Home/End, Esc e digitação para pular até a opção.
O valor selecionado precisa ser legível no gatilho fechado; não confie só no placeholder para comunicar o que está escolhido.

Componentes relacionados

Vizinhos que resolvem o problema parecido. Os links são resolvidos contra o registro.

Referência da API

Extraída do TypeScript de @voxmente/ui a cada build. Se divergir do código, o código mudou.

SelectTrigger

Prop	Tipo	Padrão
size	"md" \| "sm"	"md"

Também aceita as props de Base UI e React, incluindo className e os atributos de DOM.

Select, SelectContent, SelectGroup, SelectItem, SelectLabel, SelectScrollDownButton, SelectScrollUpButton, SelectSeparator, SelectValue não têm props próprias — aceitam apenas as props herdadas, incluindo className e os atributos de DOM.

Pendência editorial: exemplo em contexto de produto. A lacuna aparece aqui em vez de ser preenchida com orientação inventada.

Origem do dado

Orientação, acessibilidade e relacionados: documentação
Anatomia: exemplo desta página
Demonstrações e playground: componente real de @voxmente/ui
Referência da API: TypeScript do pacote
Cor, espaçamento e raio das demonstrações: tokens de theme.css