Select

Escolhe uma ou várias opções de uma lista que abre sob demanda.

O Select é para escolher entre cinco ou mais opções conhecidas, como a Origem de um Template ou a UF de destino. Para duas ou três opções visíveis, prefira RadioButtonGroup; para filtrar por texto, use um campo de busca.

import { Label, ListBox, Select } from "@rastreio-x/ui";

Padrão

A composição leva Label, Select.Trigger (valor e indicador) e Select.Popover com um ListBox. Cada item tem id e textValue.

Origem do Template

Playground

Alterne variante e estados do campo; abra a lista para conferir o resultado.

Origem do Template

Controles

variant

placeholder

isRequired

isDisabled

isInvalid

fullWidth

Conteúdo

import { Label, ListBox, Select } from "@rastreio-x/ui";

<Select placeholder="Escolha uma Origem">
  <Label>Origem do Template</Label>
  <Select.Trigger>
    <Select.Value />
    <Select.Indicator />
  </Select.Trigger>
  <Select.Popover>
    <ListBox>
      <ListBox.Item id="sp" textValue="São Paulo">
        São Paulo
        <ListBox.ItemIndicator />
      </ListBox.Item>
      <ListBox.Item id="mg" textValue="Belo Horizonte">
        Belo Horizonte
        <ListBox.ItemIndicator />
      </ListBox.Item>
    </ListBox>
  </Select.Popover>
</Select>

Variantes

primary tem sombra suave; secondary não tem, e é a variante para usar dentro de cartões e outras superfícies.

Variante primary

Variante secondary

Com descrição

Description fica abaixo do gatilho e explica onde a escolha aparece.

TransportadoraAparece na Página pública do Cliente.

Vários valores

selectionMode="multiple" no Select e no ListBox permite marcar mais de uma opção. O valor mostra a lista escolhida.

UFs de Destino

Controlado

Com value e onChange você guarda a escolha no estado.

Estado da Versão

Selecionado: Rascunho

Desabilitado

O campo todo (isDisabled) ou só algumas opções (disabledKeys). Diga no texto da opção por que ela não está disponível.

Origem do Template

Origem com opção bloqueada

Com botão de limpar

Select.ClearButton limpa a escolha com o mouse. No teclado, Backspace ou Delete limpam o valor do gatilho.

Transportadora

Anatomia

Select
├── Select.ClearButton
├── Select.Indicator
├── Select.Popover
├── Select.Trigger
└── Select.Value

Select.Trigger: o botão que abre a lista, com Select.Value e Select.Indicator.
Select.ClearButton: limpa a escolha (opcional).
Select.Popover: a camada flutuante que contém o ListBox.
ListBox.Item e ListBox.ItemIndicator: as opções e o sinal de selecionada.

Propriedades

Raiz (Select):

Select
Prop	Tipo	Padrão	Descrição
`allowsEmptyCollection`	`boolean`	-	Permite abrir a lista mesmo sem itens.
`aria-label`	`string`	-	Nome acessível, lido por leitores de tela quando não há rótulo visível.
`autoComplete`	`string`	-	Tipo de preenchimento automático que o navegador pode oferecer.
`autoFocus`	`boolean`	-	Foca o elemento ao renderizar.
`children`	`ChildrenOrFunction<SelectRenderProps>`	-	Conteúdo do componente.
`className`	`ClassNameOrFunction<SelectRenderProps>`	`'react-aria-Select'`	Classes CSS aplicadas ao elemento.
`defaultOpen`	`boolean`	-	Abre o elemento na primeira renderização (não controlado).
`defaultSelectedKey`	`Key \| null`	-	Chave selecionada inicialmente (não controlado).
`defaultValue`	`ValueType<M>`	-	Valor inicial, para uso não controlado.
`disabledKeys`	`Iterable<Key>`	-	Chaves dos itens desabilitados: não podem ser focados nem selecionados.
`excludeFromTabOrder`	`boolean`	-	Tira o elemento da ordem do Tab. Evite, salvo quando há outro caminho pelo teclado.
`form`	`string`	-	Id do `<form>` ao qual o elemento está associado.
`fullWidth`	`boolean`	-	Ocupa toda a largura disponível.
`id`	`string`	-	Identificador único do elemento.
`isDisabled`	`boolean`	-	Desabilita o componente: sem foco, clique nem envio.
`isInvalid`	`boolean`	-	Marca o valor como inválido e mostra o estado de erro.
`isOpen`	`boolean`	-	Controla se o elemento está aberto (controlado).
`isRequired`	`boolean`	-	Exige um valor antes de enviar o formulário.
`items`	`Iterable<T, M>`	-	Itens a renderizar (coleção dinâmica).
`name`	`string`	-	Nome do campo enviado com o formulário.
`onChange`	`((value: ChangeValueType<M>) => void)`	-	Chamada quando o valor ou a seleção muda.
`onClear`	`(() => void)`	-	Chamada ao limpar o valor.
`onOpenChange`	`((isOpen: boolean) => void)`	-	Chamada quando o elemento abre ou fecha.
`onSelectionChange`	`((key: Key \| null) => void)`	-	Chamada quando a seleção muda.
`placeholder`	`string`	`'Select an item' (localized)`	Texto exibido quando nada foi escolhido.
`render`	`DOMRenderFunction<'div', SelectRenderProps>`	-	Troca o elemento DOM padrão por outro, mantendo o comportamento e as props do componente.
`selectedKey`	`Key \| null`	-	Chave selecionada (controlado).
`selectionMode`	`M`	`'single'`	`single` (padrão) escolhe uma opção; `multiple` permite várias.
`shouldCloseOnSelect`	`boolean`	-	Fecha o menu ao escolher um item.
`style`	`StyleOrFunction<SelectRenderProps>`	-	Estilos em linha aplicados ao elemento.
`validate`	`((value: ValidationType<M>) => ValidationError \| true \| null \| undefined)`	-	Função de validação: devolve a mensagem de erro, ou `true` ou `null` quando o valor é válido.
`validationBehavior`	`'native' \| 'aria'`	`'native'`	Como validar: `native` usa a validação do navegador; `aria` só marca o estado e anuncia o erro.
`value`	`ValueType<M>`	-	Valor atual (controlado). Em campos de formulário, é o valor enviado.
`variant`	`'primary' \| 'secondary'`	-	Estilo: `primary` (com sombra suave) ou `secondary` (sem sombra, para uso dentro de cartões).

Gatilho (Select.Trigger):

Select.Trigger
Prop	Tipo	Padrão	Descrição
`aria-label`	`string`	-	Nome acessível, lido por leitores de tela quando não há rótulo visível.
`autoFocus`	`boolean`	-	Foca o elemento ao renderizar.
`children`	`ChildrenOrFunction<ButtonRenderProps>`	-	Conteúdo do componente.
`className`	`ClassNameOrFunction<ButtonRenderProps>`	`'react-aria-Button'`	Classes CSS aplicadas ao elemento.
`excludeFromTabOrder`	`boolean`	-	Tira o elemento da ordem do Tab. Evite, salvo quando há outro caminho pelo teclado.
`form`	`string`	-	Id do `<form>` ao qual o elemento está associado.
`formAction`	`string \| ((formData: FormData) => void \| Promise<void>)`	-	URL ou função que processa o envio; sobrescreve a ação do formulário.
`formEncType`	`string`	-	Codificação dos dados enviados pelo formulário.
`formMethod`	`string`	-	Método HTTP do envio do formulário.
`formNoValidate`	`boolean`	-	Desativa a validação nativa do formulário no envio.
`formTarget`	`string`	-	Janela de destino do envio; sobrescreve a do formulário.
`id`	`string`	-	Identificador único do elemento.
`isDisabled`	`boolean`	-	Desabilita o componente: sem foco, clique nem envio.
`isPending`	`boolean`	-	Estado de carregamento: bloqueia novos cliques, mantém o foco e anuncia o estado a leitores de tela.
`name`	`string`	-	Nome do campo enviado com o formulário.
`onPress`	`((e: PressEvent) => void)`	-	Chamada ao soltar o clique, o toque ou a tecla sobre o elemento.
`preventFocusOnPress`	`boolean`	-	Impede que o foco vá para o elemento ao pressioná-lo. Pode prejudicar a acessibilidade.
`render`	`DOMRenderFunction<'button', ButtonRenderProps>`	-	Troca o elemento DOM padrão por outro, mantendo o comportamento e as props do componente.
`style`	`StyleOrFunction<ButtonRenderProps>`	-	Estilos em linha aplicados ao elemento.
`type`	`'button' \| 'submit' \| 'reset'`	`'button'`	Tipo do elemento; define o comportamento nativo (em botões, `button`, `submit` ou `reset`).
`value`	`string`	-	Valor atual (controlado). Em campos de formulário, é o valor enviado.

Animações

CSS
indicativo

A lista abre e fecha com opacity e transform em transição curta (150 ms), e o indicador gira. Com prefers-reduced-motion, a folha global da fachada reduz a transição a 0,01 ms.

Acessibilidade

O gatilho é um botão com aria-haspopup="listbox" e aria-expanded; a lista tem papel listbox.
Teclado: Enter, Espaço ou seta para baixo abrem; setas navegam; digitar a inicial salta para a opção; Enter escolhe; Esc fecha e devolve o foco ao gatilho.
O Label dá o nome acessível e deve estar sempre visível.
isRequired e isInvalid expõem aria-required e aria-invalid.

Boas práticas

Faça

Rótulo visível, opções em Title Case curto e uma opção padrão quando fizer sentido.

Evite

Placeholder no lugar do rótulo, ou um Select para duas opções que cabiam em botões de rádio.

Mantenha as opções em ordem previsível (alfabética ou por frequência).
Opção indisponível aparece bloqueada com o motivo, não desaparece.
Use secondary dentro de cartões e superfícies.
Para mais de 20 opções, ofereça busca.

Relacionados

ListBox a lista usada dentro do Select.
RadioButtonGroup para poucas opções sempre visíveis.
TextField para texto livre.