Menu Button

1.8.0

O padrão **Menu Button** é um elemento interativo cujo objetivo é oferecer acesso rápido a uma seção ou ação específica dentro de uma listagem de acessos (Menu).

import React, { useState } from "react";
import { MenuButton } from "@nimbus-ds/patterns";
import { HomeIcon } from "@nimbus-ds/icons";

const Example: React.FC = () => {
  const [active, setActive] = useState(false);
  const handleActive = () => setActive(!active);

  return (
    <MenuButton
      label="Menu button"
      startIcon={HomeIcon}
      onClick={handleActive}
      active={active}
    />
  );
};

export default Example;

Implementação

Instale o componente via terminal.

npm install @nimbus-ds/menubutton

Menu Button

Quando usar

Quando se precisa mostrar múltiplas ações relacionadas com um objeto (ex. editar, duplicar, eliminar).
Em tooltips com ações opcionais relacionadas ao fluxo de trabalho do usuário.
Quando se precisa mostrar uma listagem de acessos onde podem existir categorias principais de navegação e subcategorias

Quando não usar

Quando há apenas uma ação disponível: nesse caso deve ser mostrado como botão direto.
Quando as ações são primárias ou de alta frequência de uso.

Critérios de usabilidade e produtividade

Agrupa ações relacionadas para minimizar o ruído visual e manter a interface focada.
Reduz a carga cognitiva ao organizar funções de forma previsível e contextual.
Compatível com ações em lote se utilizado em conjunto com seleções múltiplas.

Acessibilidade

Suporte completo de teclado: Tab para navegar, Enter ou Space para abrir, setas para deslocar-se.
Roles e atributos ARIA corretos (aria-haspopup, aria-expanded, aria-controls, menuitem).
Assegurar foco visível ao abrir o menu.
Áreas táteis adequadas em dispositivos móveis (mínimo 44x44px).

Anatomia

O Menu Button se compõe de:

Botão com ícone (⋮ ou similar).
Menu suspenso com uma lista de ações secundárias.
Opções com texto e, opcionalmente, ícones.
Separadores para agrupar ações quando necessário.

Dependências

IconButton
tooltip
Icon
Text

Variantes

Default: Ícone + texto.
With tag: Item com tag. Utiliza-se para comunicar atributos da seção, como "novo" ou "novidade".
With badge: Item com badge. Utiliza-se para mostrar quantidades ou notificações numéricas, por exemplo, a quantidade de vendas.
With ícone: Item com ícone. Utiliza-se para indicar um comportamento específico, como redirecionamentos ou abertura em uma nova aba.
Accordion button: Item acionável que desdobra opções secundárias ou complementares.

Do and Don'ts

✅ Do

Usar ícones descritivos junto ao texto para melhorar a compreensão.
Usar para agrupar ações.
Ordenar as opções por relevância e frequência.
Assegurar uma experiência fluida com teclado e screen readers.
Usar ícones quando agregarem claridade.

❌ Don't

Colocar a ação principal da interface dentro do menu.
Usar o Menu Button com uma única opção.
Não proporcionar feedback de foco ao abrir.
Repetir ações já visíveis fora do menu.

Props

Propriedades adicionais são repassadas ao elemento <MenuButton>. Consulte a documentação do elemento button para ver a lista de atributos aceitos pelo elemento <MenuButton>.

MenuButton

Name	Type	Default	Description
as	'button' 'a' React.ElementType	''	The underlying element to render — either a HTML element name or a React component.
label	string		Text label for the button.
onClick	() => void;		Function executed when clicking the button.
startIcon	React.FC<IconProps>		Sets an icon element on the left of the button.
active	boolean		Sets the state of the button as active/inactive.
children	React.ReactNode		Inner components displayed on the right of the button component.
expanded	boolean		Controlled override for menu expansion state. This prop does not manage internal state and is not forwarded to the DOM as an attribute. It is used only for layout and visual state determination. If not provided, the expanded state will be determined by the context.

MenuButton.Accordion

Name	Type	Description
children*	React.ReactNode	Content of the menu.
menuButton*	React.ReactNode	It will be the accordion anchor and can contain all the props available in the MenuButton component's API.
contentid*	string	Required ID used to maintain correct component accessibility, it will be passed on to MenuButtonAccordion's children.
open	boolean	Changes the component usage so that control of open and close is controlled from outside the component.
active	boolean	Sets the state of the button as active/inactive.
expanded	boolean	Whether the MenuButtonAccordion is expanded. If `undefined`, it follows `MenuExpandContext`. If provided, it overrides the context.