Select
Fechado
Aberto
Dentro de campo
Agrupado por família
Nos três tamanhos
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
| Prop | Tipo | Padrão |
|---|---|---|
actionsRef0.4.0Uma ref para as ações imperativas. | RefObject<SelectRootActions | null> | sem padrão |
autoComplete0.4.0Dá ao navegador uma dica para o preenchimento automático. | string | sem padrão |
defaultOpen0.4.0Se a lista do select começa aberta. | boolean | false |
defaultValue0.4.0O valor inicial do select, no modo não controlado. | SelectInputValue<Value, Multiple> | null | sem padrão |
disabled0.4.0Se a peça deve ignorar a interação do usuário. | boolean | false |
form0.4.0Identifica o formulário dono do campo oculto. | string | sem padrão |
highlightItemOnHover0.4.0Se passar o ponteiro sobre os itens os destaca. | boolean | true |
inputRef0.4.0Uma ref para acessar o campo oculto. | Ref<HTMLInputElement> | sem padrão |
isItemEqualToValue0.4.0A 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.0Os itens que a lista do select renderiza. | readonly Group<any>[]readonly { label: ReactNode; value: any; }[]Record<string, ReactNode> | sem padrão |
itemToStringLabel0.4.0Quando 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.0Quando 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.0Se o select aberto fica em estado modal. | boolean | true |
multiple0.4.0Se mais de um item pode ser escolhido. | Multiple | false |
name0.4.0Identifica o campo quando o formulário é enviado. | string | sem padrão |
onOpenChange0.4.0Chamado quando a lista do select abre ou fecha. | ((open: boolean, eventDetails: SelectRootOpenChangeEventDetails) => void) | sem padrão |
onOpenChangeComplete0.4.0Chamado depois que as animações terminam, quando a lista do select abre ou fecha. | ((open: boolean) => void) | sem padrão |
onValueChange0.4.0Chamado quando o valor do select muda. | ((value: SelectOutputValue<Value, Multiple> | (Multiple extends true ? never : null), eventDetails: SelectRootChangeEventDetails) => void) | sem padrão |
open0.4.0Se a lista do select está aberta agora. | boolean | sem padrão |
readOnly0.4.0Se o usuário fica impedido de escolher outra opção da lista do select. | boolean | false |
required0.4.0Se o usuário precisa escolher um valor antes de enviar o formulário. | boolean | false |
sizeTamanho do gatilho, o mesmo vocabulario e a mesma altura do Input. | ControlSize | "md" |
value0.4.0O valor do select. | SelectInputValue<Value, Multiple> | null | sem 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.mdA 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>
| Prop | Tipo |
|---|---|
alignAlinhamento no eixo do lado escolhido. | Align |
finalFocus0.4.0O elemento que recebe o foco quando a lista do select fecha. | booleanRefObject<HTMLElement | null>((closeType: InteractionType) => void | boolean | HTMLElement | null) |
mobileSheetAbaixo de 640px a lista abre como folha encostada embaixo, em largura cheia e acima do teclado, como o calendario. | boolean |
render0.4.0Troca o elemento HTML da peça por outra tag, ou a compõe com outro componente. | ComponentRenderFn<HTMLProps, SelectPopupState> | ReactElement<unknown, string | JSXElementConstructor<any>> |
sideLado preferido do gatilho. | Side |
sideOffsetDistancia 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.mdUma 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.
| Prop | Tipo |
|---|---|
renderTroca 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.mdUma 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.
| Prop | Tipo | Padrão |
|---|---|---|
disabled0.4.0Se a peça deve ignorar a interação do usuário. | boolean | false |
label0.4.0O texto usado para achar o item na busca por digitação. | string | sem padrão |
nativeButton0.4.0Se a peça renderiza um `<button>` nativo quando é trocada pela prop `render`. | boolean | false |
render0.4.0Troca 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.0Um valor único que identifica este item do select. | any | null |
Além destas, a peça aceita className, style, id e children, repassados ao elemento de baixo.
SelectSeparator
/select-separator.mdA 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.
| Prop | Tipo | Padrão |
|---|---|---|
orientationA orientação do separador. | Orientation | "horizontal" |
renderTroca 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.mdO 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".
| Prop | Tipo | Padrão |
|---|---|---|
disabled0.4.0Se a peça deve ignorar a interação do usuário. | boolean | sem padrão |
nativeButton0.4.0Se a peça renderiza um `<button>` nativo quando é trocada pela prop `render`. | boolean | true |
render0.4.0Troca 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.mdO 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.
| Prop | Tipo | Padrão |
|---|---|---|
placeholder0.4.0O que o gatilho mostra sem escolha. | ReactNode | "Selecione" |
render0.4.0Troca 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.