Menu
Ações da linha
Quais colunas mostrar
Ordenar por
Com submenu
import { Menu } from '@rivocode/ui'Quando usar
Menu de ações, típico dos três pontinhos de uma linha de tabela.
Compõe com MenuTrigger, MenuContent, MenuItem, MenuGroup e
MenuSeparator. O título de grupo é a propriedade label do MenuGroup, não
uma peça separada.
O menu também escolhe, e não só age: MenuCheckboxItem liga e desliga uma opção
sem fechar o painel (o "quais colunas mostrar" de uma listagem), e
MenuRadioGroup com MenuRadioItem faz a escolha única, o "ordenar por". Os
dois trazem o aria-checked de item de menu e a navegação por seta e por
primeira letra, que um Popover com Checkbox dentro não tem.
Quando um ramo merece painel próprio, MenuSubmenu com MenuSubmenuTrigger
abre ao lado. E o item que navega é MenuLinkItem, que sai como <a> de
verdade.
tone="danger" no item que apaga. Renderiza em portal, então exige o
RivoProvider.
O portal muda o lugar no DOM, mas não na árvore do React, e é pela árvore que
o evento sobe. Por isso o MenuContent para ali o clique, o duplo clique e o
botão direito: o item escolhido num menu de três pontinhos dentro de uma linha
clicável, ou dentro de um ContextMenuTrigger, não dispara o onClick da
linha nem o do gatilho. O menu fecha do mesmo jeito.
O gatilho que é só ícone é o IconButton, pelo render, com o ícone como
filho do gatilho:
<Menu>
<MenuTrigger render={<IconButton variant="ghost" label="Mais ações" />}>
<MoreHorizontal />
</MenuTrigger>
<MenuContent>
<MenuItem>Duplicar</MenuItem>
</MenuContent>
</Menu>
Quando não usar
Para escolher o valor de um campo de formulário, use Select: o Menu executa
ações, e não guarda resposta para enviar. O "ordenar por" e o "quais colunas"
ficam aqui porque mudam a vista na hora, pelo MenuRadioGroup e pelo
MenuCheckboxItem.
Navegação de topo de site, que lista lugares e não ações, é NavigationMenu.
Conteúdo livre ancorado num botão, como um filtro com campos, é Popover. E a
barra de Arquivo e Editar de uma ferramenta é Menubar, que coordena vários
menus lado a lado.
No React Native
Traduz como folha de baixo, nunca popup ancorado: a lista sobe do pé da tela com o title no topo, e children é a área que abre no toque longo. As ações simples vêm por actions, uma por linha.
Grupo, separador e item marcado atravessam com os nomes do web, por content: MenuItem (com tone e onSelect), MenuGroup com label, MenuSeparator, MenuCheckboxItem (checked e onCheckedChange) e MenuRadioGroup (value e onValueChange) com MenuRadioItem. O MenuItem fecha a folha antes de chamar o onSelect; o marcado não fecha, como no web, e a pessoa vê a marca mudar. Tudo é controlado, como em todo o pacote nativo, e o leitor de tela ouve caixa de seleção e opção de rádio, com o estado. Não há MenuSubmenu: um nível só cabe numa folha.
<Menu
open={aberto}
onOpenChange={setAberto}
title="Pedidos"
content={
<>
<MenuRadioGroup label="Ordenar por" value={ordem} onValueChange={setOrdem}>
<MenuRadioItem value="data">Data</MenuRadioItem>
<MenuRadioItem value="valor">Valor</MenuRadioItem>
</MenuRadioGroup>
<MenuSeparator />
<MenuCheckboxItem checked={arquivados} onCheckedChange={setArquivados}>
Mostrar arquivados
</MenuCheckboxItem>
</>
}
/>
API
| Prop | Tipo | Padrão |
|---|---|---|
actionsRef0.4.0Uma ref para as ações imperativas. | RefObject<MenuRootActions | null> | sem padrão |
closeParentOnEsc0.4.0Num submenu, decide se o Esc fecha o menu inteiro ou só o submenu atual. | boolean | false |
defaultOpen0.4.0Se o menu começa aberto. | boolean | false |
defaultTriggerId0.4.0ID do gatilho ao qual o menu está associado. | string | null | sem padrão |
disabled0.4.0Se a peça deve ignorar a interação do usuário. | boolean | false |
handle0.4.0Um elo para associar o menu a um gatilho. | MenuHandle<Payload> | sem padrão |
highlightItemOnHover0.4.0Se passar o ponteiro sobre os itens os destaca. | boolean | true |
loopFocus0.4.0Se o foco do teclado volta ao primeiro item ao chegar no fim da lista pelas setas. | boolean | true |
modal0.4.0Se o menu aberto fica em estado modal. | boolean | true |
onItemHighlightedChamado quando um item ganha ou perde o destaque. | ((highlightedItem: HTMLElement | undefined, eventDetails: MenuRootHighlightEventDetails) => void) | sem padrão |
onOpenChange0.4.0Chamado quando o menu abre ou fecha. | ((open: boolean, eventDetails: MenuRootChangeEventDetails) => void) | sem padrão |
onOpenChangeComplete0.4.0Chamado depois que as animações terminam, quando o menu abre ou fecha. | ((open: boolean) => void) | sem padrão |
open0.4.0Se o menu está aberto agora. | boolean | sem padrão |
orientation0.4.0A orientação visual do menu. | MenuRootOrientation | "vertical" |
triggerId0.4.0ID do gatilho ao qual o menu está associado. | string | null | sem padrão |
Partes
Menu 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.
MenuCheckboxItem
/menu-checkbox-item.mdUm item do menu que liga e desliga uma opção, sem fechar o menu.
É o menu de "Colunas" de uma listagem: quais colunas da tabela de projetos
aparecem. Cada item guarda o próprio estado com defaultChecked, ou responde a
checked e onCheckedChange quando quem manda é a tela.
Marcar não fecha o menu (closeOnClick nasce false, como na Base UI),
porque quem escolhe colunas escolhe várias de uma vez.
<MenuContent>
<MenuGroup label="Mostrar na listagem">
<MenuCheckboxItem defaultChecked disabled>Nome</MenuCheckboxItem>
<MenuCheckboxItem defaultChecked>Responsável</MenuCheckboxItem>
<MenuCheckboxItem>Plano</MenuCheckboxItem>
</MenuGroup>
</MenuContent>
Partes
classNames alcança o indicator, que é a coluna da marca. Ela existe mesmo no
item desmarcado de propósito: o indicador da Base UI só monta quando o item está
ligado, e sem uma coluna fixa o texto de todas as linhas andava para o lado a
cada clique. A largura é a mesma do SelectItem e do ComboboxItem, para as
três listas alinharem o texto na mesma coluna.
Quando não usar
Para uma escolha entre alternativas que se excluem (ordenar por data ou por
nome), use MenuRadioItem dentro de um MenuRadioGroup: o ponto diz que
escolher esta desescolhe a de cima, o que a marca de certo não diz.
E não troque por um Checkbox solto dentro de um Popover, que era o caminho
que sobrava antes desta peça. Ele custa as duas coisas que só o menu dá: o
aria-checked de item de menu, que é como o leitor de tela anuncia a linha, e a
navegação por seta e por primeira letra que a lista de menu já traz. Um Popover
é um painel com conteúdo qualquer; ninguém anda nele com o teclado como se anda
num menu.
Quando as opções são muitas e pedem busca, o menu não é o lugar: a lista com
campo de digitar é Combobox com multiple.
| Prop | Tipo | Padrão |
|---|---|---|
checkedSe o item de marcar está marcado agora. | boolean | sem padrão |
classNamesClasse por parte: `indicator`, a coluna que guarda a marca. | Partial<Record<"indicator", string>> | sem padrão |
closeOnClickSe o menu fecha quando o item é clicado. | boolean | false |
defaultCheckedSe o item de marcar começa marcado. | boolean | false |
disabledSe a peça deve ignorar a interação do usuário. | boolean | false |
labelSubstitui o texto usado na busca por digitação e no filtro. | string | sem padrão |
nativeButtonSe a peça renderiza um `<button>` nativo quando é trocada pela prop `render`. | boolean | false |
onCheckedChangeChamado quando o item de marcar é marcado ou desmarcado. | ((checked: boolean, eventDetails: MenuRootChangeEventDetails) => void) | sem padrão |
onClickO tratador de clique do item do menu. | ((event: BaseUIEvent<MouseEvent<HTMLDivElement, MouseEvent>>) => void) | sem padrão |
renderTroca o elemento HTML da peça por outra tag, ou a compõe com outro componente. | ComponentRenderFn<HTMLProps, MenuCheckboxItemState> | ReactElement<unknown, string | JSXElementConstructor<any>> | sem padrão |
tone | "danger""neutral"null | sem padrão |
Além destas, a peça aceita className, style, id e children, repassados ao elemento de baixo.
MenuContent
/menu-content.mdO painel flutuante do menu, com portal, posicionamento e a virada de lado quando não cabe.
Usa a mesma casca visual do SelectContent e do TooltipContent: o que
flutua nesta biblioteca se parece de propósito. E se posiciona igual: side,
align e sideOffset significam a mesma coisa nas cinco, e abrem a 6px do
gatilho quando ninguém pede outra folga.
No celular, abaixo de 640px, o painel vira folha encostada embaixo, em largura
cheia e com o fundo escurecido, ao alcance do polegar, como no SelectContent.
mobileSheet={false} devolve o painel preso ao gatilho.
<MenuContent side="top" align="end">
<MenuItem>Baixar PDF</MenuItem>
</MenuContent>
| Prop | Tipo |
|---|---|
alignAlinhamento no eixo do lado escolhido. | Align |
finalFocus0.4.0O elemento que recebe o foco quando o menu 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, MenuPopupState> | 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.
MenuGroup
/menu-group.mdUm grupo de itens com título.
O rótulo vem junto no label de propósito: a Base UI exige que ele viva dentro
de um grupo, e expor as duas peças separadas só criava uma forma de usar errado
que quebra na tela, não no teste de tipo.
| Prop | Tipo |
|---|---|
classNamesClasse por parte: `label`, o titulo do grupo. | Partial<Record<"label", string>> |
label0.4.0Titulo do grupo. | string |
render0.4.0Troca o elemento HTML da peça por outra tag, ou a compõe com outro componente. | ComponentRenderFn<HTMLProps, MenuGroupState> | ReactElement<unknown, string | JSXElementConstructor<any>> |
Além destas, a peça aceita className, style, id e children, repassados ao elemento de baixo.
MenuItem
/menu-item.mdUma ação do menu.
O ícone entra sem size: todo SVG dentro do item sai com 16px, inclusive no
ContextMenu e no Menubar, que usam o mesmo item.
tone="danger" pinta o que destrói. Use só no que não tem volta, se tudo é
vermelho, nada é. Item desativado continua na lista, porque sumir com a opção
esconde que ela existe.
| Prop | Tipo | Padrão |
|---|---|---|
closeOnClick0.4.0Se o menu fecha quando o item é clicado. | boolean | true |
disabled0.4.0Se a peça deve ignorar a interação do usuário. | boolean | false |
label0.4.0Substitui o texto usado na busca por digitação e no filtro. | string | sem padrão |
nativeButton0.4.0Se a peça renderiza um `<button>` nativo quando é trocada pela prop `render`. | boolean | false |
onClick0.4.0O tratador de clique do item do menu. | ((event: BaseUIEvent<MouseEvent<HTMLDivElement, MouseEvent>>) => void) | sem padrão |
render0.4.0Troca o elemento HTML da peça por outra tag, ou a compõe com outro componente. | ComponentRenderFn<HTMLProps, MenuItemState> | ReactElement<unknown, string | JSXElementConstructor<any>> | sem padrão |
tone0.4.0 | "danger""neutral"null | sem padrão |
Além destas, a peça aceita className, style, id e children, repassados ao elemento de baixo.
MenuLinkItem
/menu-link-item.mdO item do menu que navega, e por isso sai como <a> de verdade.
É o "Meu perfil" do menu do avatar. O que se ganha é o que só a âncora tem: o botão do meio abre em outra aba, o botão direito copia o endereço, e a barra do navegador mostra para onde o item leva antes do clique.
<MenuContent>
<MenuLinkItem href="/perfil">Meu perfil</MenuLinkItem>
<MenuLinkItem render={<NavLink to="/assinatura" />}>Assinatura</MenuLinkItem>
</MenuContent>
Com roteador de uma página só, passe o componente de link dele em render: o
elemento é seu, e a peça só empresta a pele e o comportamento de menu.
closeOnClick nasce true aqui, e na Base UI nasce false. O motivo é a
navegação pelo cliente: sem recarregar a página ninguém desmonta o menu, e ele
ficava aberto flutuando sobre a tela nova. Quem quiser o comportamento da Base UI
passa closeOnClick={false}.
Quando não usar
Para o que acontece na mesma tela (duplicar, exportar, cancelar), use
MenuItem. Âncora que não leva a lugar nenhum (href="#" com onClick) engana
as três affordances acima, e é pior do que um item comum.
Um menu inteiro de links é um menu de navegação, e não de ações: aí a peça é
NavigationMenu, ou a Sidebar quando os destinos são as seções do painel.
| Prop | Tipo | Padrão |
|---|---|---|
closeOnClickSe o menu fecha quando o item é clicado. | boolean | true |
labelSubstitui o texto usado na busca por digitação e no filtro. | string | sem padrão |
renderTroca o elemento HTML da peça por outra tag, ou a compõe com outro componente. | ComponentRenderFn<DetailedHTMLProps<AnchorHTMLAttributes<HTMLAnchorElement>, HTMLAnchorElement>, MenuLinkItemState> | ReactElement<...> | sem padrão |
Além destas, a peça aceita className, style, id e children, repassados ao elemento de baixo.
MenuRadioGroup
/menu-radio-group.mdO grupo de escolha única dentro do menu, e quem guarda o valor escolhido.
É o "Ordenar por" de uma listagem: uma ordem de cada vez. O valor vive aqui, e
não em cada item: defaultValue para deixar com a peça, value mais
onValueChange para deixar com a tela.
O título vem no label, pelo mesmo motivo do MenuGroup: a Base UI liga o
aria-labelledby do grupo ao título que mora dentro dele, e um título escrito
por fora não nomeia grupo nenhum (falha que não quebra tipo, só o anúncio).
<MenuRadioGroup defaultValue="criacao" label="Ordenar por">
<MenuRadioItem value="criacao" closeOnClick>Data de criação</MenuRadioItem>
<MenuRadioItem value="nome" closeOnClick>Nome</MenuRadioItem>
</MenuRadioGroup>
Partes
classNames alcança o label, o mesmo título que o MenuGroup escreve.
Quando não usar
Para opções que se acumulam (quais colunas mostrar, quais situações incluir no
filtro), use MenuCheckboxItem: lá cada linha é independente, aqui uma linha
apaga a anterior.
Se as opções cabem na tela e comparar entre elas importa, o menu esconde o que
deveria estar à vista: RadioGroup mostra todas de uma vez, e ToggleGroup
resolve as duas ou três que viram botão. O menu é para quando a escolha não
merece ocupar espaço permanente na barra.
| Prop | Tipo | Padrão |
|---|---|---|
classNamesClasse por parte: `label`, o titulo do grupo. | Partial<Record<"label", string>> | sem padrão |
defaultValueO valor do item de opção que começa escolhido, no modo não controlado. | any | sem padrão |
disabledSe a peça deve ignorar a interação do usuário. | boolean | false |
labelTitulo do grupo: "Ordenar por". | string | sem padrão |
onValueChangeChamada quando o valor escolhido muda. | ((value: any, eventDetails: MenuRootChangeEventDetails) => void) | sem padrão |
renderTroca o elemento HTML da peça por outra tag, ou a compõe com outro componente. | ComponentRenderFn<HTMLProps, MenuRadioGroupState> | ReactElement<unknown, string | JSXElementConstructor<any>> | sem padrão |
valueO valor do item de opção escolhido agora, no modo controlado. | any | sem padrão |
Além destas, a peça aceita className, style, id e children, repassados ao elemento de baixo.
MenuRadioItem
/menu-radio-item.mdUma opção de escolha única no menu: "por data de criação", "por nome".
Sempre dentro de um MenuRadioGroup, que é quem guarda o valor. O value é
obrigatório: é ele que o grupo compara para saber qual linha está escolhida.
O ponto no lugar da marca de certo não é decoração: ele diz que escolher esta desescolhe a de cima.
Como na Base UI, escolher não fecha o menu. Quando a escolha encerra o
assunto, e ordenar costuma encerrar, passe closeOnClick.
Partes
classNames alcança o indicator, a coluna que guarda o ponto (a mesma
largura do MenuCheckboxItem, para os dois alinharem o texto quando aparecem no
mesmo painel).
Quando não usar
Para ligar e desligar cada opção por conta, use MenuCheckboxItem.
Para uma ação que acontece e acaba (baixar o PDF, cancelar o pedido), use
MenuItem: aria-checked num item que não guarda estado nenhum diz ao leitor de
tela que há uma escolha marcada onde não há.
| Prop | Tipo | Padrão |
|---|---|---|
valueobrigatóriaO valor do item de opção. | any | sem padrão |
classNamesClasse por parte: `indicator`, a coluna que guarda o ponto. | Partial<Record<"indicator", string>> | sem padrão |
closeOnClickSe o menu fecha quando o item é clicado. | boolean | false |
disabledSe a peça deve ignorar a interação do usuário. | boolean | false |
labelSubstitui o texto usado na busca por digitação e no filtro. | string | sem padrão |
nativeButtonSe a peça renderiza um `<button>` nativo quando é trocada pela prop `render`. | boolean | false |
onClickO tratador de clique do item do menu. | ((event: BaseUIEvent<MouseEvent<HTMLDivElement, MouseEvent>>) => void) | sem padrão |
renderTroca o elemento HTML da peça por outra tag, ou a compõe com outro componente. | ComponentRenderFn<HTMLProps, MenuRadioItemState> | ReactElement<unknown, string | JSXElementConstructor<any>> | sem padrão |
tone | "danger""neutral"null | sem padrão |
Além destas, a peça aceita className, style, id e children, repassados ao elemento de baixo.
MenuSeparator
/menu-separator.mdA linha entre grupos de ação.
Separa o que muda a tela do que muda o dado, e o comum do destrutivo. Duas separações seguidas viram enfeite.
| Prop | Tipo | Padrão |
|---|---|---|
orientation0.4.0A orientação do separador. | Orientation | "horizontal" |
render0.4.0Troca o elemento HTML da peça por outra tag, ou a compõe com outro componente. | ComponentRenderFn<HTMLProps, SeparatorState> | 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.
MenuSubmenu
/menu-submenu.mdUm ramo do menu, que abre ao lado.
Não pinta elemento nenhum: é só estado. Dentro dele vão o MenuSubmenuTrigger,
que é o item que abre o ramo, e um MenuContent, que é o mesmo painel do menu
de cima.
O lado não precisa ser pedido. A Base UI abre o ramo em inline-end quando o
pai é um menu, e vira para o outro lado sozinha quando não cabe. Passar side
aqui é para quem tem motivo, não obrigação.
<MenuContent>
<MenuItem>Duplicar</MenuItem>
<MenuSubmenu>
<MenuSubmenuTrigger>Exportar</MenuSubmenuTrigger>
<MenuContent>
<MenuItem>Etiqueta de envio</MenuItem>
<MenuItem>Comprovante em PDF</MenuItem>
</MenuContent>
</MenuSubmenu>
</MenuContent>
O MenuSubmenuTrigger traz a seta que avisa que há mais adiante, e classNames
alcança ela pelo nome indicator. O item fica aceso enquanto o ramo está
aberto: sem isso o realce sai assim que o ponteiro entra no painel filho, e nada
mais liga um ao outro.
Quando não usar
Um nível resolve quase tudo. Dois já é uma árvore, e árvore com o mouse em cima
é como andar na diagonal sem perder a linha: quem escorrega fecha o ramo inteiro
e recomeça. Passando disso, Dialog ou uma tela própria custam menos a quem usa.
Para o menu que abre no botão direito sobre uma área, o gatilho é outro:
ContextMenu. E para a navegação principal do site, com painéis largos e links,
é NavigationMenu: o submenu daqui é uma lista de ações, e não um mapa de
seções.
| Prop | Tipo | Padrão |
|---|---|---|
actionsRefUma ref para as ações imperativas. | RefObject<MenuRootActions | null> | sem padrão |
closeParentOnEscNum submenu, decide se o Esc fecha o menu inteiro ou só o submenu atual. | boolean | false |
defaultOpenSe o menu começa aberto. | boolean | false |
disabledSe a peça deve ignorar a interação do usuário. | boolean | false |
highlightItemOnHoverSe passar o ponteiro sobre os itens os destaca. | boolean | true |
loopFocusSe o foco do teclado volta ao primeiro item ao chegar no fim da lista pelas setas. | boolean | true |
onItemHighlightedChamado quando um item ganha ou perde o destaque. | ((highlightedItem: HTMLElement | undefined, eventDetails: MenuRootHighlightEventDetails) => void) | sem padrão |
onOpenChangeChamado quando o menu abre ou fecha. | ((open: boolean, eventDetails: MenuRootChangeEventDetails) => void) | sem padrão |
onOpenChangeCompleteChamado depois que as animações terminam, quando o menu abre ou fecha. | ((open: boolean) => void) | sem padrão |
openSe o menu está aberto agora. | boolean | sem padrão |
orientationA orientação visual do menu. | MenuRootOrientation | "vertical" |
MenuTrigger
/menu-trigger.mdO que abre o menu.
Sem estilo próprio de propósito: quase sempre ele envolve um Button por
render, e um estilo aqui brigaria com o do botão.
| Prop | Tipo | Padrão |
|---|---|---|
closeDelay0.4.0Quanto esperar antes de fechar o menu aberto pelo passar do ponteiro. | number | 0 |
delay0.4.0Quanto esperar antes de o menu poder abrir pelo passar do ponteiro. | number | 100 |
disabled0.4.0Se a peça deve ignorar a interação do usuário. | boolean | false |
handle0.4.0Um elo para associar o gatilho a um menu. | MenuHandle<unknown> | sem padrão |
nativeButton0.4.0Se a peça renderiza um `<button>` nativo quando é trocada pela prop `render`. | boolean | true |
openOnHover0.4.0Se o menu abre também quando o ponteiro passa sobre o gatilho. | boolean | sem padrão |
payload0.4.0Um dado a entregar ao menu quando ele abre. | unknown | sem padrão |
render0.4.0Troca o elemento HTML da peça por outra tag, ou a compõe com outro componente. | ComponentRenderFn<HTMLProps, MenuTriggerState> | 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.