ListBox

Lista de opções selecionáveis, ou de ações, navegável por teclado.

O ListBox mostra opções que a pessoa escolhe (uma ou várias) ou ações que ela aciona. É a lista por baixo do Select e serve também sozinha, como seletor de transportadora. Para linhas ricas com dados use ListView; para tabelas, DataGrid.

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

Padrão

Cada ListBox.Item tem id e textValue. O ListBox.ItemIndicator marca a opção escolhida. Informe aria-label para nomear a lista.

Seleção múltipla

selectionMode="multiple" permite marcar vários itens; defaultSelectedKeys define os iniciais.

Itens desabilitados

disabledKeys bloqueia itens. Mantenha-os visíveis e explique no texto.

Com selectionMode="none" e onAction, o ListBox vira um menu de ações. Itens destrutivos usam variant="danger".

Nenhuma ação ainda

Anatomia

ListBox
├── ListBox.Item
├── ListBox.ItemIndicator
└── ListBox.Section

ListBox.Item: uma opção, com rótulo e descrição.
ListBox.ItemIndicator: sinal de selecionada.
ListBox.Section: agrupa itens com um cabeçalho.

Propriedades

Raiz (ListBox):

ListBox
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 \| FocusStrategy`	-	Foca o elemento ao renderizar.
`children`	`React.ReactNode \| ((item: T) => React.ReactNode)`	-	Conteúdo do componente.
`className`	`string`	`'react-aria-ListBox'`	Classes CSS aplicadas ao elemento.
`defaultSelectedKeys`	`Iterable<Key> \| 'all'`	-	Chaves selecionadas inicialmente (não controlado).
`dependencies`	`readonly any[]`	-	Valores que invalidam o cache dos itens em coleções dinâmicas.
`disabledKeys`	`Iterable<Key>`	-	Chaves dos itens desabilitados: não podem ser focados nem selecionados.
`disallowEmptySelection`	`boolean`	-	Impede ficar sem nenhum item selecionado.
`dragAndDropHooks`	`DragAndDropHooks<NoInfer<T>>`	-	Hooks de `useDragAndDrop` para arrastar e reordenar itens.
`escapeKeyBehavior`	`'none' \| 'clearSelection'`	`'clearSelection'`	O que a tecla Esc faz: limpar a seleção ou nada.
`id`	`string`	-	Identificador único do elemento.
`items`	`Iterable<T>`	-	Itens a renderizar (coleção dinâmica).
`layout`	`'grid' \| 'stack'`	`'stack'`	Organiza os itens em pilha (`stack`, padrão) ou em grade (`grid`).
`onAction`	`((key: Key) => void)`	-	Chamada quando o item é acionado.
`onSelectionChange`	`((keys: Selection) => void)`	-	Chamada quando a seleção muda.
`orientation`	`Orientation`	`'vertical'`	Orientação do componente: `horizontal` ou `vertical`.
`render`	`DOMRenderFunction<'div', ListBoxRenderProps>`	-	Troca o elemento DOM padrão por outro, mantendo o comportamento e as props do componente.
`renderEmptyState`	`((props: ListBoxRenderProps) => React.ReactNode)`	-	Conteúdo exibido quando não há itens.
`selectedKeys`	`Iterable<Key> \| 'all'`	-	Chaves selecionadas (controlado).
`selectionBehavior`	`SelectionBehavior`	`'toggle'`	Modelo de interação da seleção: `toggle` marca cada item; `replace` troca a seleção.
`selectionMode`	`SelectionMode`	-	Tipo de seleção permitida: nenhuma, única ou múltipla.
`shouldFocusOnHover`	`boolean`	-	Foca o item ao passar o mouse.
`shouldFocusWrap`	`boolean`	-	Volta ao primeiro item ao passar do último.
`shouldSelectOnPressUp`	`boolean`	-	Seleciona ao soltar, em vez de ao pressionar.
`style`	`StyleOrFunction<ListBoxRenderProps>`	-	Estilos em linha aplicados ao elemento.
`variant`	`'danger' \| 'default'`	-	`danger` destaca ação destrutiva; `default` é o padrão.

Item (ListBox.Item):

ListBox.Item
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.
`children`	`ChildrenOrFunction<ListBoxItemRenderProps>`	-	Conteúdo do componente.
`className`	`string`	`'react-aria-ListBoxItem'`	Classes CSS aplicadas ao elemento.
`download`	`string \| boolean`	-	Faz o navegador baixar o arquivo do link; um texto sugere o nome.
`href`	`string`	-	URL de destino do link.
`hrefLang`	`string`	-	Idioma do recurso do link.
`id`	`Key`	-	Identificador único do elemento.
`isDisabled`	`boolean`	-	Desabilita o componente: sem foco, clique nem envio.
`onAction`	`(() => void)`	-	Chamada quando o item é acionado.
`onPress`	`((e: PressEvent) => void)`	-	Chamada ao soltar o clique, o toque ou a tecla sobre o elemento.
`ping`	`string`	-	URLs notificadas quando o link é seguido.
`referrerPolicy`	`React.HTMLAttributeReferrerPolicy`	-	Quanto da origem (referrer) enviar ao seguir o link.
`rel`	`string`	-	Relação entre a página atual e o recurso do link.
`render`	`((props: React.DetailedHTMLProps<React.HTMLAttributes<HTMLDivElement>, HTMLDivE…`	-	Troca o elemento DOM padrão por outro, mantendo o comportamento e as props do componente.
`routerOptions`	`undefined`	-	Opções do roteador do lado do cliente.
`style`	`StyleOrFunction<ListBoxItemRenderProps>`	-	Estilos em linha aplicados ao elemento.
`target`	`React.HTMLAttributeAnchorTarget`	-	Janela de destino do link (`_blank`, `_self`).
`textValue`	`string`	-	Texto do item, usado na busca por digitação e na acessibilidade.
`value`	`unknown`	-	Valor atual (controlado). Em campos de formulário, é o valor enviado.
`variant`	`'danger' \| 'default'`	-	`danger` destaca ação destrutiva; `default` é o padrão.

Animações

Sem movimento
indicativo

Sem animação própria: o item muda de fundo no hover e no foco. Dentro de um Select, quem anima é o popover.

Acessibilidade

Papel listbox com itens option; aria-multiselectable quando há seleção múltipla.
Setas navegam, Home e End vão às pontas, digitar salta por inicial, Enter ou Espaço escolhem.
Em selectionMode="none", o item é acionado com Enter ou clique.
O estado de selecionado vem de aria-selected; o indicador reforça sem depender só da cor.

Boas práticas

Faça

Rótulo e descrição curtos, e um indicador claro do que está selecionado.

Evite

Misturar escolha e ação na mesma lista, ou esconder itens indisponíveis sem explicar.

Para escolher entre poucas opções, a lista aberta evita um clique extra.
Para listas longas, junte com um campo de busca.
Use variant="danger" só em ações destrutivas e confirme antes.

Relacionados

Select a mesma lista dentro de um campo que abre.
Checkbox para marcar opções em um formulário.
DataGrid para dados em colunas.