Dropdown

Abre um menu de ações ou de escolhas a partir de um botão.

O Dropdown agrupa ações secundárias sob um botão: importar CSV, duplicar uma versão, mover uma conversa. Para escolher um valor de um campo, use Select; para mostrar uma ajuda ao passar o mouse, Tooltip; para conteúdo livre, Popover.

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

Padrão

O gatilho é o primeiro filho (um Button), seguido de Dropdown.Popover com um Dropdown.Menu. Cada Dropdown.Item tem id e textValue, e o menu tem aria-label. Use onAction para tratar a escolha.

Com ícones e descrições

Ícone decorativo (aria-hidden) à esquerda e Description explica o efeito da ação.

Ação destrutiva e item desabilitado

variant="danger" marca a ação destrutiva, separada das outras por um Separator. disabledKeys bloqueia um item: diga no texto por que ele não está disponível.

Seleção múltipla

selectionMode com selectedKeys e onSelectionChange transforma o menu em filtro; Dropdown.ItemIndicator mostra o check.

Atalhos de teclado

Kbd com slot="keyboard" mostra o atalho à direita do item.

Gatilho só com ícone

Como no cartão do kanban de suporte: o botão é só um EllipsisIcon, então precisa de aria-label que diga o objeto da ação.

Anatomia

Dropdown
├── Dropdown.Item
├── Dropdown.ItemIndicator
├── Dropdown.Menu
├── Dropdown.Popover
├── Dropdown.Section
├── Dropdown.SubmenuIndicator
├── Dropdown.SubmenuTrigger
└── Dropdown.Trigger

Dropdown: guarda o estado de abertura.
Dropdown.Popover: a camada flutuante (escolha o placement).
Dropdown.Menu: a lista de itens, com aria-label.
Dropdown.Item: cada ação, com Label, Description e Kbd opcionais.
Dropdown.ItemIndicator: sinal de selecionado (check ou ponto).
Dropdown.Section, Dropdown.SubmenuTrigger e Dropdown.SubmenuIndicator: seções e submenus.

Propriedades

Dropdown:

Dropdown
Prop	Tipo	Padrão	Descrição
`children`*	`React.ReactNode`	-	Conteúdo do componente.
`className`	`string`	-	Classes CSS aplicadas ao elemento.
`defaultOpen`	`boolean`	-	Abre o elemento na primeira renderização (não controlado).
`isOpen`	`boolean`	-	Controla se o elemento está aberto (controlado).
`onOpenChange`	`((isOpen: boolean) => void)`	-	Chamada quando o elemento abre ou fecha.
`trigger`	`MenuTriggerType`	`'press'`	Nome do componente que abriu a camada (exposto em `data-trigger`).

Dropdown.Menu:

Dropdown.Menu
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-Menu'`	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.
`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).
`onAction`	`((key: Key, value: T) => void)`	-	Chamada quando o item é acionado.
`onClose`	`(() => void)`	-	Chamada quando o elemento fecha.
`onSelectionChange`	`((keys: Selection) => void)`	-	Chamada quando a seleção muda.
`render`	`DOMRenderFunction<'div', MenuRenderProps>`	-	Troca o elemento DOM padrão por outro, mantendo o comportamento e as props do componente.
`renderEmptyState`	`(() => React.ReactNode)`	-	Conteúdo exibido quando não há itens.
`selectedKeys`	`Iterable<Key> \| 'all'`	-	Chaves selecionadas (controlado).
`selectionMode`	`SelectionMode`	-	Tipo de seleção permitida: nenhuma, única ou múltipla.
`shouldCloseOnSelect`	`boolean`	-	Fecha o menu ao escolher um item.
`shouldFocusWrap`	`boolean`	-	Volta ao primeiro item ao passar do último.
`style`	`StyleOrFunction<MenuRenderProps>`	-	Estilos em linha aplicados ao elemento.

Dropdown.Item:

Dropdown.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<MenuItemRenderProps>`	-	Conteúdo do componente.
`className`	`string`	`'react-aria-MenuItem'`	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.
`shouldCloseOnSelect`	`boolean`	-	Fecha o menu ao escolher um item.
`style`	`StyleOrFunction<MenuItemRenderProps>`	-	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.

Dropdown.Popover:

Dropdown.Popover
Prop	Tipo	Padrão	Descrição
`children`*	`React.ReactNode`	-	Conteúdo do componente.
`aria-label`	`string`	-	Nome acessível, lido por leitores de tela quando não há rótulo visível.
`arrowBoundaryOffset`	`number`	`0`	Distância mínima entre a borda da seta e a borda da camada.
`arrowRef`	`RefObject<Element \| null>`	-	Referência ao elemento da seta.
`boundaryElement`	`Element`	`document.body`	Elemento que serve de limite para o posicionamento.
`className`	`ClassNameOrFunction<PopoverRenderProps>`	`'react-aria-Popover'`	Classes CSS aplicadas ao elemento.
`containerPadding`	`number`	`12`	Espaço mínimo entre a camada e a borda do contêiner.
`crossOffset`	`number`	`0`	Deslocamento adicional no eixo transversal entre a camada e o âncora.
`defaultOpen`	`boolean`	-	Abre o elemento na primeira renderização (não controlado).
`getTargetRect`	`((target: Element) => DOMRect \| null \| undefined)`	`target.getBoundingClientRect()`	Substitui o retângulo do alvo; útil para posicionar em relação a um ponto.
`isEntering`	`boolean`	-	Indica que a animação de entrada está em andamento.
`isExiting`	`boolean`	-	Indica que a animação de saída está em andamento.
`isKeyboardDismissDisabled`	`boolean`	`false`	Impede que a tecla Esc feche a camada.
`isNonModal`	`boolean`	-	Camada não modal: elementos fora dela continuam acessíveis a tecnologias assistivas.
`isOpen`	`boolean`	-	Controla se o elemento está aberto (controlado).
`maxHeight`	`number`	-	Altura máxima da camada; por padrão ocupa o espaço disponível na janela.
`offset`	`number`	`8`	Deslocamento adicional no eixo principal entre a camada e o âncora.
`onOpenChange`	`((isOpen: boolean) => void)`	-	Chamada quando o elemento abre ou fecha.
`placement`	`Placement`	`'bottom'`	Lado em que a lista abre em relação ao gatilho (padrão `bottom`).
`render`	`DOMRenderFunction<'div', PopoverRenderProps>`	-	Troca o elemento DOM padrão por outro, mantendo o comportamento e as props do componente.
`scrollRef`	`RefObject<Element \| null>`	`overlayRef`	Referência à região rolável da camada.
`shouldCloseOnInteractOutside`	`((element: Element) => boolean)`	-	Decide se uma interação fora da camada a fecha.
`shouldFlip`	`boolean`	`true`	Inverte o lado quando não há espaço suficiente.
`shouldSkipAnimation`	`boolean`	-	Mostra e esconde sem animação de entrada ou saída.
`shouldUpdatePosition`	`boolean`	`true`	Atualiza a posição automaticamente ao rolar ou redimensionar.
`style`	`StyleOrFunction<PopoverRenderProps>`	-	Estilos em linha aplicados ao elemento.
`trigger`	`string`	-	Nome do componente que abriu a camada (exposto em `data-trigger`).
`triggerRef`	`RefObject<Element \| null>`	-	Referência ao elemento a que a camada se posiciona.
`UNSTABLE_portalContainer`	`Element`	`document.body`	Elemento que recebe o portal da camada. Interface instável.

Animações

CSS
indicativo

O menu abre e fecha com opacity e transform em transição curta de CSS, e o indicador do item aparece na escolha. Com prefers-reduced-motion, a folha global da fachada reduz as transições a 0,01 ms.

Acessibilidade

Papel menu com itens menuitem; o gatilho expõe aria-haspopup e aria-expanded.
Teclado: Enter, Espaço ou seta para baixo abrem; setas navegam; digitar a inicial salta para o item; Enter ativa; Esc fecha e devolve o foco ao gatilho.
O menu precisa de aria-label (ou aria-labelledby).
Botão só com ícone precisa de aria-label descrevendo o objeto ("Mover para… conversa de Marina Souza").
A ação destrutiva é marcada também por texto, não só pela cor danger.

Boas práticas

Faça

Rótulos de verbo mais objeto, ação destrutiva por último e separada.

Evite

Mais de sete itens sem seções, ou esconder a única ação principal da tela dentro de um menu.

Ação principal vai num botão visível; o menu leva as secundárias.
Para escolher um valor num formulário, use Select.
Mantenha o texto do item curto; use Description só quando a ação não for óbvia.
Importante: Header (título de seção do menu) ainda não é exportado pela fachada; hoje separe seções com Separator.

Relacionados

Select para escolher um valor em campo.
Popover para conteúdo livre sob um gatilho.
Button como gatilho do menu.
Tooltip para dicas curtas.