DropdownMenu

A dropdown menu that displays a list of actionable items in a popup triggered by a button. Use to present action options as a next step in a process, or to offer contextual actions without cluttering the interface. Like the menus of macOS and iOS, the row under the pointer when it is released is the row that acts, the highlight follows a held mouse or finger, a mouse opens it on press and can drag straight into it, and a finger held on the trigger opens it with the finger down.

Installation

npm install @astryxdesign/core@0.7.1 @astryxdesign/theme-neutral@0.7.1 @stylexjs/stylex@0.19.0

Requires React 19+, base CSS and a Theme provider. See Setup.

Dropdown Menu

A dropdown menu that displays a list of actionable items in a popup triggered by a button. Use to present action options as a next step in a process, or to offer contextual actions without cluttering the interface. Like the menus of macOS and iOS, the row under the pointer when it is released is the row that acts, the highlight follows a held mouse or finger, a mouse opens it on press and can drag straight into it, and a finger held on the trigger opens it with the finger down.

Usage guidance

• Keep menu items concise and action-oriented so users can scan options quickly.
• Use sections and dividers to group related actions when the menu has many items.
• For a short, flat action set, use presentation="bottom-sheet" when product policy calls for a modal touch surface.
• Use presentation="adaptive" when the same short action set should remain anchored on pointer layouts and become a BottomSheet on compact coarse-pointer layouts.
• For a hierarchy that cannot fit as adjacent flyouts on a compact touch surface, a product may explicitly use a drill-in interaction with a Back action.
• Choose presentation explicitly in product code. A compact, coarse-pointer, hover-free media query is one useful policy, but DropdownMenu does not impose a universal device breakpoint.
• When the content is no longer a short list of immediate actions, reevaluate the interaction and choose a component that matches the actual task; content traits alone do not determine the component.
• Avoid: Use a DropdownMenu for navigation; use a navigation component instead.
• Avoid: Place more than 10–12 items in a single menu without grouping them into sections.

Theming API

{
  "targets": [
    {
      "className": "astryx-dropdown-menu",
      "visualProps": [
        "presentation"
      ]
    },
    {
      "className": "astryx-dropdown-menu-item",
      "visualProps": [
        "size",
        "variant"
      ]
    },
    {
      "className": "astryx-dropdown-menu-radio",
      "visualProps": [
        "size"
      ],
      "states": [
        "checked",
        "disabled"
      ]
    },
    {
      "className": "astryx-dropdown-menu-section-heading"
    },
    {
      "className": "astryx-dropdown-menu-divider"
    },
    {
      "className": "astryx-dropdown-menu-indicator-icon"
    }
  ],
  "vars": [
    {
      "name": "--_dropdown-menu-radius",
      "description": "Border radius of the menu popup",
      "default": "var(--radius-element)",
      "private": true
    },
    {
      "name": "--_dropdown-menu-padding",
      "description": "Inner padding of the menu popup",
      "default": "var(--spacing-1)",
      "private": true
    }
  ],
  "derived": [
    {
      "property": "borderRadius",
      "vars": [
        "--_dropdown-menu-radius"
      ]
    },
    {
      "property": "padding",
      "vars": [
        "--_dropdown-menu-padding"
      ]
    }
  ]
}

DropdownMenuItem

Anatomy

• Trigger button: Button that opens and closes the selected menu presentation.
• Trigger indicator icon: Optional trailing chevron shown by a labeled trigger when hasChevron is enabled.
• Pointer menu surface: Anchored top-level or nested menu panel used by the pointer presentation.
• Pointer action row: Action, selectable option, or submenu trigger row in an anchored menu.
• Icon-rendered item icon: Optional semantic or component icon rendered through Icon at the start of an action row.
• Caller-rendered item start content: Optional arbitrary React content rendered directly at the start of an action row.
• Checkbox indicator: Decorative shared checkbox indicator for a checkbox action row.
• Radio indicator: Decorative shared radio indicator with an additional menu-owned target.
• Pointer section heading: Heading that labels a group of rows in an anchored menu: a data-driven section or a compound DropdownMenuGroup.
• Pointer divider: Divider between groups in an anchored menu.
• Pointer submenu indicator icon: Trailing chevron that identifies an action row as a nested flyout trigger.
• Touch sheet frame: BottomSheet panel, content area, handle, and optional scrim that host touch actions.
• Touch menu surface: Menu-owned content panel rendered inside the touch sheet frame.
• Touch heading: Current action-sheet title, updated when a nested action view is opened.
• Touch action list: Spacious List that groups actions in the touch presentation.
• Touch action row: ListItem button used for an action or drill-in entry in the touch presentation.
• Touch divider: Divider between action groups in the touch presentation.

Dropdown Menu Checkbox Item

An independently checkable option inside DropdownMenu. The row owns menuitemcheckbox semantics while the shared Indicator supplies decorative checkbox paint.

Theming API

{
  "targets": [
    {
      "className": "astryx-dropdown-menu-item",
      "visualProps": [
        "size"
      ]
    }
  ]
}

Anatomy

• Checkable row: The menuitemcheckbox root that owns the accessible name, checked state, focus, and activation.
• Label/content: Caller content laid out by Item: the required label plus optional description, icon, and end content.
• Checkbox marker: Decorative shared Indicator chrome that visualizes checked and disabled state without adding a second control.

Dropdown Menu Divider

A horizontal rule separating groups of rows in a compound menu. Renders role="separator", so it is never a stop in the arrow-key order. The data-driven equivalent is the {type: "divider"} entry in items; both modes render this component, so they look and theme identically.

Theming API

{
  "targets": [
    {
      "className": "astryx-dropdown-menu-divider"
    }
  ]
}

Dropdown Menu Group

A titled group of rows in a compound menu. Renders role="group" named by its heading; the heading is plain text, not a menuitem, so arrow keys and typeahead skip it. The data-driven equivalent is the {type: "section", title, items} entry in items; the heading shares its typography and theme target.

Theming API

{
  "targets": [
    {
      "className": "astryx-dropdown-menu-section-heading"
    }
  ]
}

Dropdown Menu Item

Helper component for custom item rendering with consistent styling. Host attributes and DOM event handlers (aria-, data-, id, drag and drop) reach the row root, the element carrying role="menuitem".

Dropdown Menu Radio Group

A single-select group of radio menu items (role="group" of menuitemradio). Owns the selected value and lays its items out with the menu's inter-item gap.

Dropdown Menu Radio Item

A single option in a DropdownMenuRadioGroup (role="menuitemradio"). Must be used inside a DropdownMenuRadioGroup.

Dropdown Menu Submenu

A single menu row that reveals a nested flyout of its own items. The row adopts DropdownMenuItem semantics (label / icon / description / isDisabled); its children become the flyout content. Opens inline-end with viewport auto-flip; Right/Enter/Space opens and focuses the first item, Left/Escape closes and returns focus to the trigger (Right/Left swap in RTL). On a phone (a coarse pointer, decided when the menu opened) the row drills in instead: its rows replace the menu's rows in the same box, led by a Back row named "Back to <parent>", and Back, Escape or ArrowLeft return to the row. Host attributes and DOM event handlers (aria-, data-, id) reach the trigger row, the element carrying role="menuitem" and aria-haspopup="menu"; a caller's handlers run after the row's own, except for the keys that open the flyout (the open arrow, Enter, Space) and a click on a disabled row. For data-driven menus, give a menu item a nested items array instead of using this component directly.

Examples

• Dropdown Menu Group: A compound-mode menu whose rows are titled in groups. Each DropdownMenuGroup renders a role="group" named by its heading; arrow keys and typeahead skip the heading.
• Dropdown Menu Item: Dropdown menu with custom-rendered items using DropdownMenuItem for icons and descriptions.
• Dropdown Menu: A button that opens a dropdown menu with action items. The menu starts open for preview.
• DropdownMenu — Actions: Action menu with dividers separating safe and destructive operations. Use for row-level actions on items like documents, projects, or records.
• DropdownMenu — Adaptive presentation: Chooses a bottom sheet for compact touch surfaces and an anchored popover otherwise. The media query is product policy, while DropdownMenu owns both presentations.
• DropdownMenuGroup — Selectable rows: Titled groups around a radio group and checkbox rows — the rows the data API cannot express, which is why the heading lives in compound mode.
• DropdownMenuItem — Basic: Dropdown menu items with labels and secondary descriptions. Use DropdownMenuItem to render custom menu entries with consistent styling.
• DropdownMenu — Icon Trigger: Overflow menu triggered by an icon-only button with no chevron or label text. Use for row-level actions in tables, cards, or lists where a text button would take too much space.
• DropdownMenu — Disabled: Menu with selectively disabled items based on permissions. Use when some actions require higher privileges, like admin-only operations.
• DropdownMenu — Sections: Menu items organized into titled sections for easy scanning. Use when you have 6+ actions that fall into distinct categories, like Create vs Manage.
• DropdownMenu — Submenu: Action menu with a nested submenu. Hover or Right arrow opens the flyout; Left arrow / Escape closes it. Use to group related destinations or secondary actions without crowding the top level.

Complete example dependencies

Some examples import optional icons. The per-example install command in the examples list identifies exactly what that example needs. For all examples on this page:

npm install @heroicons/react@2.2.0