Pular para o conteúdo
Navegação

Menu

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

Ações da linha

Quais colunas mostrar

Ordenar por

Com submenu

Importar
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

PropTipoPadrão
actionsRef0.4.0

Uma ref para as ações imperativas.

RefObject<MenuRootActions | null>sem padrão
closeParentOnEsc0.4.0

Num submenu, decide se o Esc fecha o menu inteiro ou só o submenu atual.

booleanfalse
defaultOpen0.4.0

Se o menu começa aberto.

booleanfalse
defaultTriggerId0.4.0

ID do gatilho ao qual o menu está associado.

string | nullsem padrão
disabled0.4.0

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

booleanfalse
handle0.4.0

Um elo para associar o menu a um gatilho.

MenuHandle<Payload>sem padrão
highlightItemOnHover0.4.0

Se passar o ponteiro sobre os itens os destaca.

booleantrue
loopFocus0.4.0

Se o foco do teclado volta ao primeiro item ao chegar no fim da lista pelas setas.

booleantrue
modal0.4.0

Se o menu aberto fica em estado modal.

booleantrue
onItemHighlighted

Chamado quando um item ganha ou perde o destaque.

((highlightedItem: HTMLElement | undefined, eventDetails: MenuRootHighlightEventDetails) => void)sem padrão
onOpenChange0.4.0

Chamado quando o menu abre ou fecha.

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

Chamado depois que as animações terminam, quando o menu abre ou fecha.

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

Se o menu está aberto agora.

booleansem padrão
orientation0.4.0

A orientação visual do menu.

MenuRootOrientation"vertical"
triggerId0.4.0

ID do gatilho ao qual o menu está associado.

string | nullsem 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.

/menu-checkbox-item.md

Um 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>

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.

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.

PropTipoPadrão
checked

Se o item de marcar está marcado agora.

booleansem padrão
classNames

Classe por parte: `indicator`, a coluna que guarda a marca.

Partial<Record<"indicator", string>>sem padrão
closeOnClick

Se o menu fecha quando o item é clicado.

booleanfalse
defaultChecked

Se o item de marcar começa marcado.

booleanfalse
disabled

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

booleanfalse
label

Substitui o texto usado na busca por digitação e no filtro.

stringsem padrão
nativeButton

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

booleanfalse
onCheckedChange

Chamado quando o item de marcar é marcado ou desmarcado.

((checked: boolean, eventDetails: MenuRootChangeEventDetails) => void)sem padrão
onClick

O tratador de clique do item do menu.

((event: BaseUIEvent<MouseEvent<HTMLDivElement, MouseEvent>>) => void)sem padrão
render

Troca 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"nullsem padrão

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

/menu-content.md

O 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>
PropTipo
align

Alinhamento no eixo do lado escolhido.

Align
finalFocus0.4.0

O elemento que recebe o foco quando o menu 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, MenuPopupState> | 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.

Um 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.

PropTipo
classNames

Classe por parte: `label`, o titulo do grupo.

Partial<Record<"label", string>>
label0.4.0

Titulo do grupo.

string
render0.4.0

Troca 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.

Uma 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.

PropTipoPadrão
closeOnClick0.4.0

Se o menu fecha quando o item é clicado.

booleantrue
disabled0.4.0

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

booleanfalse
label0.4.0

Substitui o texto usado na busca por digitação e no filtro.

stringsem padrão
nativeButton0.4.0

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

booleanfalse
onClick0.4.0

O tratador de clique do item do menu.

((event: BaseUIEvent<MouseEvent<HTMLDivElement, MouseEvent>>) => void)sem padrão
render0.4.0

Troca 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"nullsem padrão

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

/menu-link-item.md

O 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}.

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.

PropTipoPadrão
closeOnClick

Se o menu fecha quando o item é clicado.

booleantrue
label

Substitui o texto usado na busca por digitação e no filtro.

stringsem padrão
render

Troca 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.

/menu-radio-group.md

O 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>

classNames alcança o label, o mesmo título que o MenuGroup escreve.

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.

PropTipoPadrão
classNames

Classe por parte: `label`, o titulo do grupo.

Partial<Record<"label", string>>sem padrão
defaultValue

O valor do item de opção que começa escolhido, no modo não controlado.

anysem padrão
disabled

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

booleanfalse
label

Titulo do grupo: "Ordenar por".

stringsem padrão
onValueChange

Chamada quando o valor escolhido muda.

((value: any, eventDetails: MenuRootChangeEventDetails) => void)sem padrão
render

Troca 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
value

O valor do item de opção escolhido agora, no modo controlado.

anysem padrão

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

/menu-radio-item.md

Uma 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.

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).

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á.

PropTipoPadrão
valueobrigatória

O valor do item de opção.

anysem padrão
classNames

Classe por parte: `indicator`, a coluna que guarda o ponto.

Partial<Record<"indicator", string>>sem padrão
closeOnClick

Se o menu fecha quando o item é clicado.

booleanfalse
disabled

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

booleanfalse
label

Substitui o texto usado na busca por digitação e no filtro.

stringsem padrão
nativeButton

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

booleanfalse
onClick

O tratador de clique do item do menu.

((event: BaseUIEvent<MouseEvent<HTMLDivElement, MouseEvent>>) => void)sem padrão
render

Troca 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"nullsem padrão

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

/menu-separator.md

A 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.

PropTipoPadrão
orientation0.4.0

A orientação do separador.

Orientation"horizontal"
render0.4.0

Troca 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.

/menu-submenu.md

Um 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.

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.

PropTipoPadrão
actionsRef

Uma ref para as ações imperativas.

RefObject<MenuRootActions | null>sem padrão
closeParentOnEsc

Num submenu, decide se o Esc fecha o menu inteiro ou só o submenu atual.

booleanfalse
defaultOpen

Se o menu começa aberto.

booleanfalse
disabled

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

booleanfalse
highlightItemOnHover

Se passar o ponteiro sobre os itens os destaca.

booleantrue
loopFocus

Se o foco do teclado volta ao primeiro item ao chegar no fim da lista pelas setas.

booleantrue
onItemHighlighted

Chamado quando um item ganha ou perde o destaque.

((highlightedItem: HTMLElement | undefined, eventDetails: MenuRootHighlightEventDetails) => void)sem padrão
onOpenChange

Chamado quando o menu abre ou fecha.

((open: boolean, eventDetails: MenuRootChangeEventDetails) => void)sem padrão
onOpenChangeComplete

Chamado depois que as animações terminam, quando o menu abre ou fecha.

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

Se o menu está aberto agora.

booleansem padrão
orientation

A orientação visual do menu.

MenuRootOrientation"vertical"
/menu-trigger.md

O 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.

PropTipoPadrão
closeDelay0.4.0

Quanto esperar antes de fechar o menu aberto pelo passar do ponteiro.

number0
delay0.4.0

Quanto esperar antes de o menu poder abrir pelo passar do ponteiro.

number100
disabled0.4.0

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

booleanfalse
handle0.4.0

Um elo para associar o gatilho a um menu.

MenuHandle<unknown>sem padrão
nativeButton0.4.0

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

booleantrue
openOnHover0.4.0

Se o menu abre também quando o ponteiro passa sobre o gatilho.

booleansem padrão
payload0.4.0

Um dado a entregar ao menu quando ele abre.

unknownsem padrão
render0.4.0

Troca 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.

@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.