Dropdown Menu Suspenso - Docs - Artefact

Dropdown Menu Suspenso

Overlays

Auto-interativo

Introdução

Uma lista de ações ou opções que aparece quando acionada. Suporta posicionamentos personalizados com inversão automática ao transbordar o viewport, uma seta opcional com geometria que aponta para o centro, itens de checkbox/radio/grupo, submenus em cascata, e modos de disparo por clique / hover / menu de contexto.

Uso

Dropdown básico

import { Dropdown, Button } from "../components/ui";

export default function MyPage() {
  return (
    <Dropdown
      trigger={<Button>Open Dropdown</Button>}
      items={[
        { type: "item", label: "Edit", value: "edit" },
        { type: "separator" },
        { type: "checkbox", label: "Bold", value: "bold", checked: true },
        {
          type: "radio-group",
          value: "theme",
          label: "Theme",
          items: [
            { type: "radio", label: "Light", value: "light" },
            { type: "radio", label: "Dark", value: "dark" },
          ],
        },
      ]}
    />
  );
}

Botão com menu suspenso

import { Dropdown } from "../components/ui";

export default function Page() {
  return (
    <Dropdown.Button
      type="primary"
      items={[{ type: "item", label: "Submit & Close", value: "close" }]}
      onClick={() => console.log("Primary click!")}
    >
      Submit Action
    </Dropdown.Button>
  );
}

Estilo personalizado e classNames semânticos

<Dropdown
  trigger={<Button>Styled Dropdown</Button>}
  classNames={{
    content: "custom-menu-card",
    item: "custom-menu-item"
  }}
  styles={{
    content: { boxShadow: "0 4px 20px rgba(0,0,0,0.15)" }
  }}
  items={[{ type: "item", label: "Custom Styled Item", value: "styled" }]}
/>

Seta apontando para o centro

<Dropdown
  trigger={<Button>Center Arrow</Button>}
  arrow={{ pointAtCenter: true }}
  placement="bottomRight"
  items={[{ type: "item", label: "Item 1", value: "1" }]}
/>

Grupos e submenus em cascata

<Dropdown
  trigger={<Button>Open Dropdown</Button>}
  items={[
    {
      type: "group",
      label: "File",
      items: [
        { type: "item", label: "New", value: "new" },
        { type: "item", label: "Open", value: "open" },
      ],
    },
    { type: "separator" },
    {
      type: "submenu",
      label: "Share",
      items: [
        { type: "item", label: "Email", value: "email" },
        { type: "item", label: "Link", value: "link" },
      ],
    },
  ]}
/>

Posicionamento personalizado, seta e disparo por hover

<Dropdown
  trigger={<Button>Hover Me</Button>}
  placement="bottomRight"
  triggerMode="hover"
  arrow={true}
  mouseEnterDelay={100}
  mouseLeaveDelay={150}
  items={[
    { type: "item", label: "Profile", value: "profile" },
    { type: "item", label: "Settings", value: "settings" },
    { type: "separator" },
    { type: "item", label: "Logout", value: "logout" },
  ]}
/>

Menu de contexto

Um disparador configurado como "contextMenu" abre com o clique direito, ancorado no ponteiro, em vez de se comportar como um botão:

<Dropdown
  trigger={<div>Right-click this area</div>}
  trigger={"contextMenu"}
  items={[
    { type: "item", label: "Copy", value: "copy" },
    { type: "item", label: "Paste", value: "paste" },
  ]}
/>

Estado de abertura controlado

const [open, setOpen] = useState(false);

<Dropdown
  open={open}
  onOpenChange={setOpen}
  trigger={<Button>Open Dropdown</Button>}
  items={[{ type: "item", label: "Edit", value: "edit" }]}
/>;

Construtor de páginas CMS

Este componente está disponível como um bloco menu no Construtor de páginas (content/pages/*.json) — o bloco do CMS é rotulado "Menu", mas é renderizado por meio deste componente Dropdown:

{
  "type": "menu",
  "triggerText": "Open Dropdown",
  "items": [
    { "type": "item", "label": "Edit", "value": "edit" },
    { "type": "separator" },
    { "type": "item", "label": "Delete", "value": "delete" }
  ]
}

Propriedades

Dropdown

Prop	Tipo	Descrição	Padrão
`trigger`	`JSX.Element`	Elemento que abre o menu ao ser ativado.	-
`items`	`DropdownItem[]`	Os itens do menu a renderizar.	-
`open`	`boolean`	Se o menu está aberto (controlado).	-
`defaultOpen`	`boolean`	Se o menu está aberto por padrão (não controlado).	`false`
`disabled`	`boolean`	Desabilita todos os modos de disparo e torna o disparador inerte.	`false`
`interactive`	`boolean`	Força a hidratação como ilha. Padrão `true`.	`true`

| arrow | `boolean \ | { pointAtCenter?: boolean }` | Mostra uma seta indicadora apontando do menu para o disparador. Pode se alinhar exatamente com o centro do disparador. | false |

| onOpenChange | `(open: boolean, info?: { source: 'trigger' \ | 'menu' }) => void` | Chamado quando o menu abre ou fecha. source especifica o que desencadeou a ação. | - |

| size | `"xs" \ | "sm" \ | "md" \ | "lg" \ | "xl"` | O tamanho do menu. | "md" |

Slots de classNames e styles:

root (ou positioner): O contêiner de posicionamento absoluto da sobreposição.
content: O cartão do popup contendo os itens da lista.
item: Item de lista individual (incluindo itens de checkbox e radio).
trigger: O botão/wrapper disparador principal.
arrow: O wrapper externo da seta.
arrowTip: O losango interno estilizado.

DropdownItem

Propriedade	Tipo	Descrição

Dropdown.Button (DropdownButton)

Um Button com um menu suspenso, renderizado como um grupo de botões anexados contínuo.

Prop	Tipo	Descrição	Padrão

Suporta todos os props comuns do Dropdown, como items, placement, arrow, classNames, styles, etc.

Nota

Certifique-se de que trigger aceite onMouseEnter, onMouseLeave, onFocus, e onClick — o elemento disparador é clonado no lugar com esses (e os atributos ARIA/data-* relevantes) anexados, em vez de envolvido.

Limitações

A ilha interativa posiciona o menu em relação ao próprio wrapper do seu disparador (position: absolute, não um portal): ela inverte para o lado oposto quando o posicionamento solicitado transbordaria do viewport, e limita o eixo transversal para que o menu nunca seja renderizado fora da tela. Ela não rastreia contêineres de scroll nem resize observers da forma como o Floating UI faz — o reposicionamento só é executado novamente no resize da janela enquanto está aberto, e rolar a página move o menu junto com o disparador de forma gratuita. Um menu aberto de dentro de um contêiner com scroll ou overflow: hidden profundo ainda pode ser recortado visualmente por esse contêiner, a mesma compensação que Popover e Tooltip fazem.

Os menus de contexto e os submenus são a exceção: como não estão ancorados à caixa de um disparador (um menu de contexto abre no ponteiro; um submenu abre ao lado de um item de menu), eles são posicionados com position: fixed e coordenadas calculadas manualmente, e são executados novamente em Escape/scroll/resize como o resto do menu.

Cada submenu é sua própria ilha interativa aninhada, delimitada por meio de um marcador data-overlay-root para que a lógica de posicionamento e clique-fora de um menu pai não alcance o conteúdo próprio de um submenu (e vice-versa). Selecionar um item comum fecha todos os níveis de menu abertos pelos quais ele borbulha; alternar um item de checkbox/radio dentro de qualquer nível mantém toda a pilha aberta.

A animação de saída _closed (slide-fade-out) é reproduzida antes que o menu seja realmente removido do layout — fechar não o oculta instantaneamente.