Menu

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 notas 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>Número</MenuCheckboxItem>
    <MenuCheckboxItem defaultChecked>Cliente</MenuCheckboxItem>
    <MenuCheckboxItem>Valor</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 valor), 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.

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.

<MenuContent side="top" align="end">
  <MenuItem>Baixar PDF</MenuItem>
</MenuContent>

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.

Uma ação do menu.

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.

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={<Link 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.

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="emissao" label="Ordenar por">
  <MenuRadioItem value="emissao" closeOnClick>Data de emissão</MenuRadioItem>
  <MenuRadioItem value="valor" closeOnClick>Valor</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.

Uma opção de escolha única no menu: "por data de emissão", "por valor".

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 a nota), 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á.

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.

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>XML da NF-e</MenuItem>
      <MenuItem>PDF do DANFE</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.

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.