Pular para o conteúdo
Formulário

Select

/componentes/select.mdmarkdown cru, para quem lê com agent em vez de olho

Fechado

Aberto

Dentro de campo

Agrupado por família

Nos três tamanhos

Importar
import { Select } from '@rivocode/ui'

Quando usar

Escolha única em lista.

Compõe com SelectTrigger, SelectValue, SelectContent e SelectItem. Lista com famílias de verdade ganha SelectGroup com SelectGroupLabel, e SelectSeparator entre uma família e outra.

Passe items com { label, value } na raiz. Sem isso o gatilho mostra o valor cru em vez do rótulo, e essa é a armadilha mais fácil de cair aqui.

Renderiza em portal, então exige o RivoProvider.

size mora na raiz, com o vocabulário do Input: sm, md (padrão) e lg, com a mesma altura, o mesmo recuo e o mesmo corpo de texto. O SelectTrigger de dentro veste o tamanho sozinho, então um filtro com Input size="sm" e Select size="sm" lado a lado fica numa linha só.

O valor escolhido fica numa linha só: longo, ele termina em reticência, e o gatilho nunca passa da largura da caixa em volta. Não é preciso className="w-full" no SelectTrigger nem truncate no SelectValue para isso. O texto começa na mesma coluna do Input, como em todo campo da casa.

<Select items={STATUS} size="sm">
  <SelectTrigger aria-label="Status">
    <SelectValue placeholder="Todos" />
  </SelectTrigger>
  <SelectContent>
    <SelectItem value="abertas">Abertas</SelectItem>
  </SelectContent>
</Select>

Quando não usar

Quando a lista é grande demais para caber na cabeça de quem escolhe, ou quando ela vem do servidor, use Combobox: ele traz a busca junto. Rolar cento e vinte cidades numa lista sem campo de digitar é o mesmo trabalho de procurar numa gaveta.

Para duas ou três opções que cabem lado a lado, o RadioGroup mostra todas de uma vez e economiza o clique de abrir. E para um liga-desliga, o Switch.

No React Native

Traduz, e a forma de escrever é outra. No web o Select pede items na raiz e as quatro partes (SelectTrigger, SelectValue, SelectContent, SelectItem); no nativo ele é uma tag só (<Select items={…} value={…} onValueChange={…} label="Período" />), e a lista abre numa folha de baixo, que é o idioma da plataforma para escolher. O label é obrigatório: é por ele que o leitor de tela anuncia o gatilho, papel que no web era do SelectTrigger.

Famílias de opções entram pelo mesmo items, em grupos { label, items } - a forma que o items do web também aceita. A folha vira uma SectionList, e cada label de grupo é anunciado como cabeçalho, no lugar do SelectGroupLabel.

API

PropTipoPadrão
actionsRef0.4.0

Uma ref para as ações imperativas.

RefObject<SelectRootActions | null>sem padrão
autoComplete0.4.0

Dá ao navegador uma dica para o preenchimento automático.

stringsem padrão
defaultOpen0.4.0

Se a lista do select começa aberta.

booleanfalse
defaultValue0.4.0

O valor inicial do select, no modo não controlado.

SelectInputValue<Value, Multiple> | nullsem padrão
disabled0.4.0

Se a peça deve ignorar a interação do usuário.

booleanfalse
form0.4.0

Identifica o formulário dono do campo oculto.

stringsem padrão
highlightItemOnHover0.4.0

Se passar o ponteiro sobre os itens os destaca.

booleantrue
inputRef0.4.0

Uma ref para acessar o campo oculto.

Ref<HTMLInputElement>sem padrão
isItemEqualToValue0.4.0

A comparação que decide se o valor de um item do select é o valor escolhido.

((itemValue: Value, value: Value) => boolean)sem padrão
items0.4.0

Os itens que a lista do select renderiza.

readonly Group<any>[]readonly { label: ReactNode; value: any; }[]Record<string, ReactNode>sem padrão
itemToStringLabel0.4.0

Quando o valor dos itens é objeto (`<Select.Item value={object}>`), converte o objeto no texto mostrado no gatilho.

((itemValue: Value) => string)sem padrão
itemToStringValue0.4.0

Quando o valor dos itens é objeto (`<Select.Item value={object}>`), converte o objeto no texto enviado com o formulário.

((itemValue: Value) => string)sem padrão
modal0.4.0

Se o select aberto fica em estado modal.

booleantrue
multiple0.4.0

Se mais de um item pode ser escolhido.

Multiplefalse
name0.4.0

Identifica o campo quando o formulário é enviado.

stringsem padrão
onOpenChange0.4.0

Chamado quando a lista do select abre ou fecha.

((open: boolean, eventDetails: SelectRootOpenChangeEventDetails) => void)sem padrão
onOpenChangeComplete0.4.0

Chamado depois que as animações terminam, quando a lista do select abre ou fecha.

((open: boolean) => void)sem padrão
onValueChange0.4.0

Chamado quando o valor do select muda.

((value: SelectOutputValue<Value, Multiple> | (Multiple extends true ? never : null), eventDetails: SelectRootChangeEventDetails) => void)sem padrão
open0.4.0

Se a lista do select está aberta agora.

booleansem padrão
readOnly0.4.0

Se o usuário fica impedido de escolher outra opção da lista do select.

booleanfalse
required0.4.0

Se o usuário precisa escolher um valor antes de enviar o formulário.

booleanfalse
size

Tamanho do gatilho, o mesmo vocabulario e a mesma altura do Input.

ControlSize"md"
value0.4.0

O valor do select.

SelectInputValue<Value, Multiple> | nullsem padrão

Partes

Select se monta com estas peças. Todas vivem nesta página, porque separar cada uma num endereço obrigaria a abrir seis abas para montar uma tela.

SelectContent

/select-content.md

A lista flutuante do select.

Nasce com a largura do gatilho e rola sozinha quando não cabe na tela. O portal usa o contêiner do RivoProvider, então o tema vale dentro dela.

side, align e sideOffset posicionam o painel, como nas outras peças que flutuam. Pedir qualquer um dos três troca o modo de posicionamento: por padrão a lista se sobrepõe ao gatilho para alinhar o item escolhido com o texto dele, e nesse modo não há lado nem folga a respeitar. Quem não pede nada continua com o alinhamento pelo item.

No celular a lista vira folha. Abaixo de 640px ela encosta embaixo, em largura cheia, acima do teclado e com o fundo escurecido, como o calendário do DatePicker: o painel preso ao gatilho ficava pequeno para o dedo e saía cortado na borda. side, align e sideOffset não valem na folha. mobileSheet={false} mantém o painel preso ao gatilho em toda largura, para a lista curta dentro de uma barra de filtro que já mora no pé da tela.

<SelectContent side="top" align="start">
  <SelectItem value="abertas">Abertas</SelectItem>
</SelectContent>
PropTipo
align

Alinhamento no eixo do lado escolhido.

Align
finalFocus0.4.0

O elemento que recebe o foco quando a lista do select fecha.

booleanRefObject<HTMLElement | null>((closeType: InteractionType) => void | boolean | HTMLElement | null)
mobileSheet

Abaixo de 640px a lista abre como folha encostada embaixo, em largura cheia e acima do teclado, como o calendario.

boolean
render0.4.0

Troca o elemento HTML da peça por outra tag, ou a compõe com outro componente.

ComponentRenderFn<HTMLProps, SelectPopupState> | ReactElement<unknown, string | JSXElementConstructor<any>>
side

Lado preferido do gatilho.

Side
sideOffset

Distancia entre o gatilho e o painel, em pixels.

number | OffsetFunction

Além destas, a peça aceita className, style, id e children, repassados ao elemento de baixo.

SelectGroup

/select-group.md

Uma família dentro da lista, com o SelectGroupLabel de cabeçalho.

Natureza de operação separada em entrada e saída, UF por região, plano de contas por grupo: a lista longa que tem famílias de verdade lê-se por partes, e não de cima a baixo.

O desenho é o do ComboboxGroup, e não o do MenuGroup com label: as duas são peças de formulário e listam opções, e quem troca uma pela outra ao descobrir que a lista cresceu não deveria ter que reescrever a árvore.

<SelectContent>
  <SelectGroup>
    <SelectGroupLabel>Saída</SelectGroupLabel>
    <SelectItem value="5102">Venda de mercadoria</SelectItem>
    <SelectItem value="5915">Remessa para conserto</SelectItem>
  </SelectGroup>

  <SelectSeparator />

  <SelectGroup>
    <SelectGroupLabel>Entrada</SelectGroupLabel>
    <SelectItem value="1202">Devolução de venda</SelectItem>
  </SelectGroup>
</SelectContent>

O items da raiz continua sendo a lista inteira e plana: é por ele que o gatilho traduz o valor guardado no rótulo que a pessoa leu. O grupo arruma a lista aberta, e não o que o gatilho mostra.

O SelectGroupLabel vive dentro do grupo porque é o grupo que aponta o aria-labelledby para ele. Título escrito ao lado não nomeia nada, e nenhum tipo reclama.

Quando não usar

Quando agrupar é a tentativa de domar uma lista que ficou grande demais, o remédio é outro: Combobox, que traz a busca. Rolar cento e vinte cidades arrumadas por região continua sendo rolar cento e vinte cidades, e o cabeçalho só acrescenta altura ao caminho.

Grupo de dois itens não paga o cabeçalho que cobra. Sem famílias de verdade, a lista plana diz a mesma coisa em menos linhas.

PropTipo
render

Troca o elemento HTML da peça por outra tag, ou a compõe com outro componente.

ComponentRenderFn<HTMLProps, SelectGroupState> | ReactElement<unknown, string | JSXElementConstructor<any>>

Além destas, a peça aceita className, style, id e children, repassados ao elemento de baixo.

SelectItem

/select-item.md

Uma opção da lista.

O value é o que volta no onValueChange; o conteúdo é o que a pessoa lê. A marca de escolhido tem coluna própria, então rótulo curto e longo alinham pela mesma vertical.

PropTipoPadrão
disabled0.4.0

Se a peça deve ignorar a interação do usuário.

booleanfalse
label0.4.0

O texto usado para achar o item na busca por digitação.

stringsem padrão
nativeButton0.4.0

Se a peça renderiza um `<button>` nativo quando é trocada pela prop `render`.

booleanfalse
render0.4.0

Troca o elemento HTML da peça por outra tag, ou a compõe com outro componente.

ComponentRenderFn<HTMLProps, SelectItemState> | ReactElement<unknown, string | JSXElementConstructor<any>>sem padrão
value0.4.0

Um valor único que identifica este item do select.

anynull

Além destas, a peça aceita className, style, id e children, repassados ao elemento de baixo.

SelectSeparator

/select-separator.md

A linha entre dois grupos da lista.

Ela sai com role="presentation", e não com o role="separator" do MenuSeparator. A diferença não é de aparência: dentro de uma lista de opções, um nó com papel próprio entra na contagem que o leitor de tela anuncia ("opção 3 de 12"), e a conta passa a não bater com o que se vê.

Quando não usar

Sem SelectGroup em volta, ela separa o quê? Numa lista plana a linha vira divisão sem critério: quem lê procura o motivo do corte e não acha. Se o motivo existe, ele tem nome, e o nome é um SelectGroupLabel.

PropTipoPadrão
orientation

A orientação do separador.

Orientation"horizontal"
render

Troca o elemento HTML da peça por outra tag, ou a compõe com outro componente.

ComponentRenderFn<HTMLProps, SelectSeparatorState> | ReactElement<unknown, string | JSXElementConstructor<any>>sem padrão

Além destas, a peça aceita className, style, id e children, repassados ao elemento de baixo.

SelectTrigger

/select-trigger.md

O campo fechado do select: mostra a escolha e abre a lista.

Tem a mesma altura e a mesma borda do Input, para um formulário misto não sair desalinhado. A seta é desenhada aqui, não passe ícone por fora.

Dentro de um Field, ele acompanha a largura do campo, como o Input, e encolhe junto numa grade estreita. Solto, numa barra de filtros, nasce com 10rem no mínimo, para não mudar de largura a cada valor escolhido; em coluna estreita fora de um Field, passe className="min-w-0".

PropTipoPadrão
disabled0.4.0

Se a peça deve ignorar a interação do usuário.

booleansem padrão
nativeButton0.4.0

Se a peça renderiza um `<button>` nativo quando é trocada pela prop `render`.

booleantrue
render0.4.0

Troca o elemento HTML da peça por outra tag, ou a compõe com outro componente.

ComponentRenderFn<HTMLProps, SelectTriggerState> | ReactElement<unknown, string | JSXElementConstructor<any>>sem padrão

Além destas, a peça aceita className, style, id e children, repassados ao elemento de baixo.

SelectValue

/select-value.md

O texto do gatilho: o que está escolhido agora.

Passe items com { label, value } no Select para ele mostrar o rótulo. Sem isso ele mostra o valor cru, porque só a lista sabe traduzir um pelo outro. É contrato da Base UI, e a armadilha mais fácil de cair neste componente.

Sem escolha, o gatilho mostra "Selecione". placeholder troca o texto por um que diga o que se escolhe ("Todos os status"), e placeholder="" deixa o gatilho vazio.

PropTipoPadrão
placeholder0.4.0

O que o gatilho mostra sem escolha.

ReactNode"Selecione"
render0.4.0

Troca o elemento HTML da peça por outra tag, ou a compõe com outro componente.

ComponentRenderFn<HTMLProps, SelectValueState> | ReactElement<unknown, string | JSXElementConstructor<any>>sem padrão

Além destas, a peça aceita className, style, id e children, repassados ao elemento de baixo.

@rivocode/ui, 149 peças no catálogo. Esta página é gerada dos mesmos arquivos que alimentam o design system, então ela não envelhece sozinha.

Feito por RivoCode.