Dropdown Menu

Menu dropdown triggered by a button with keyboard navigation.

Components

Dropdown Menu

feedback

interactive

<arc-dropdown-menu>

Overview

DropdownMenu renders a click-triggered menu panel anchored below a customizable trigger element. The trigger is provided via the `trigger` named slot, and menu items are declared as `<arc-menu-item>` children in the default slot. Clicking the trigger toggles the panel open or closed, and clicking outside the component or pressing Escape dismisses it. The panel slides down with a smooth CSS transition using `opacity`, `visibility`, and `transform`. Menu items display a label and an optional keyboard shortcut hint in monospace. Dividers between groups of items are added with `<arc-menu-divider>`. When the panel is open, ArrowDown and ArrowUp cycle focus through selectable items (dividers are skipped), and Enter activates the focused item. The component dispatches an `arc-select` event with the item's label and shortcut on selection, then closes the panel and fires an `arc-close` event. DropdownMenu is designed for action menus attached to buttons: file menus, "more actions" dots, profile menus, and similar patterns. It differs from ContextMenu (which is triggered by right-click on a parent region) and from Select (which is a form control that captures a value). The trigger slot accepts any element, so you can use an `<arc-button>`, a plain `<button>`, or an icon as the toggle.

Guidelines

When to use

Provide a clear, descriptive trigger element. A button with text like "Actions" or a recognizable icon
Group related items with <arc-menu-divider>, and name a group with <arc-menu-label> rather than a disabled item
Include shortcut hints on items that have associated keyboard bindings for user education
Listen to arc-select to execute the chosen action; the event contains the item label and shortcut
Keep the item count under 10; for larger command sets, use CommandPalette instead

When not to use

Do not use DropdownMenu as a form Select replacement. It does not track a selected value
Do not place the trigger element outside the <arc-dropdown-menu> component; it must be in the trigger slot
Do not nest another DropdownMenu inside a menu item; use a flat list or CommandPalette for complex hierarchies
Do not add role="menu" or role="menuitem" yourself. The component sets both
Do not override the z-index of the panel without testing stacking context conflicts with other overlays

Features

Click-triggered panel anchored below a customizable trigger slot
Smooth CSS transition with opacity, visibility, and translateY animation
Full keyboard navigation: ArrowUp/Down cycle items, Enter selects, Escape closes
Support for `<arc-menu-item>` with label and shortcut hint, `<arc-menu-divider>` for separating groups, and `<arc-menu-label>` for naming them
Disabled items are drawn muted, skipped by the keyboard, and never selected
A trigger that fills a full-width host: give `arc-dropdown-menu` a width or `display: block`
`arc-select` event on item activation with label and shortcut in the detail
`arc-close` event when the panel is dismissed by any means
Automatic close on outside click via a document-level event listener
`aria-haspopup` and `aria-expanded` on the trigger for screen reader accessibility

Preview

Actions

Danger zone

Usage

This component requires JavaScript. No pure HTML/CSS version is available. Use the Web Component directly or a framework wrapper.

<arc-dropdown-menu>
  <button slot="trigger">File Menu</button>
  <arc-menu-item shortcut="⌘N">New File</arc-menu-item>
  <arc-menu-item shortcut="⌘O">Open</arc-menu-item>
  <arc-menu-item shortcut="⌘S">Save</arc-menu-item>
</arc-dropdown-menu>

import { DropdownMenu, MenuItem } from '@arclux/arc-ui-react';

export default function Example() {
  return (
    <DropdownMenu>
      <button slot="trigger">File Menu</button>
      <MenuItem shortcut="⌘N">New File</MenuItem>
      <MenuItem shortcut="⌘O">Open</MenuItem>
      <MenuItem shortcut="⌘S">Save</MenuItem>
    </DropdownMenu>
  );
}

<script setup>
import { DropdownMenu, MenuItem } from '@arclux/arc-ui-vue';
</script>

<template>
  <DropdownMenu>
    <button slot="trigger">File Menu</button>
    <MenuItem shortcut="⌘N">New File</MenuItem>
    <MenuItem shortcut="⌘O">Open</MenuItem>
    <MenuItem shortcut="⌘S">Save</MenuItem>
  </DropdownMenu>
</template>

<script>
  import { DropdownMenu, MenuItem } from '@arclux/arc-ui-svelte';
</script>

<DropdownMenu>
  <button slot="trigger">File Menu</button>
  <MenuItem shortcut="⌘N">New File</MenuItem>
  <MenuItem shortcut="⌘O">Open</MenuItem>
  <MenuItem shortcut="⌘S">Save</MenuItem>
</DropdownMenu>

import { Component } from '@angular/core';
import { DropdownMenu, MenuItem } from '@arclux/arc-ui-angular';

@Component({
  imports: [DropdownMenu, MenuItem],
  template: `
    <arc-dropdown-menu>
      <button slot="trigger">File Menu</button>
      <arc-menu-item shortcut="⌘N">New File</arc-menu-item>
      <arc-menu-item shortcut="⌘O">Open</arc-menu-item>
      <arc-menu-item shortcut="⌘S">Save</arc-menu-item>
    </arc-dropdown-menu>
  `,
})
export class MyComponent {}

import { DropdownMenu, MenuItem } from '@arclux/arc-ui-solid';

export default function Example() {
  return (
    <DropdownMenu>
      <button slot="trigger">File Menu</button>
      <MenuItem shortcut="⌘N">New File</MenuItem>
      <MenuItem shortcut="⌘O">Open</MenuItem>
      <MenuItem shortcut="⌘S">Save</MenuItem>
    </DropdownMenu>
  );
}

import { DropdownMenu, MenuItem } from '@arclux/arc-ui-preact';

export default function Example() {
  return (
    <DropdownMenu>
      <button slot="trigger">File Menu</button>
      <MenuItem shortcut="⌘N">New File</MenuItem>
      <MenuItem shortcut="⌘O">Open</MenuItem>
      <MenuItem shortcut="⌘S">Save</MenuItem>
    </DropdownMenu>
  );
}

API

openboolean=false: Controls whether the menu panel is visible. Toggled by clicking the trigger. Set to false when the user selects an item, clicks outside, or presses Escape.

Events

arc-close: Fired when the dropdown closes
arc-select: Fired when a menu item is selected

MenuItem

<arc-menu-item>

A single action entry inside the context menu.

displayLabel: The text to draw. label was documented as a prop and implemented as a getter over textContent with no setter and no attribute, so <arc-menu-item label="Cut"></arc-menu-item> rendered a blank item, silently, and the six generated wrappers exposed a writable label that did nothing (finding #32). It is a real property now; the text-content form stays the fallback, so every existing consumer is unaffected.
selectionValue: What arc-select reports. Falls back to the label so an item that never sets value behaves as it always did.
labelstring='': Display text for the menu item. Settable, and falls back to the element's text content when unset: <arc-menu-item label="Cut"> and <arc-menu-item>Cut</arc-menu-item> are equivalent.
shortcutstring='': Keyboard shortcut hint displayed on the right side.
iconstring='': Name of the icon to display before the label.
valuestring='': Stable identifier carried on the arc-select detail. Defaults to the label, which is fine until two items share one. Give anything a handler must act on its own value rather than matching against display text.
disabledboolean=false: Disables the item, preventing interaction.

MenuDivider

<arc-menu-divider>

A visual separator between groups of menu items.

MenuLabel

<arc-menu-label>

A heading over a group of menu items. The items after it, up to the next label, form one named group.

displayLabel
labelstring='': The heading text. Falls back to the element's text content when unset, as on arc-menu-item.

Dropdown Menu

Overview

Guidelines

When to use

When not to use

Features

Preview

Usage

API

Events

MenuItem

MenuDivider

MenuLabel

See Also

Docs

Project

Arclight