Components

DropdownMenu

Headless button-triggered menu primitives for actions and compact choices.

When to Use

Use DropdownMenu when a visible button opens a short set of commands or menu choices. Use ContextMenu when actions belong to a right-clicked target, Select when one value is chosen for a form, and Menubar for persistent application commands. Do not use a menu as ordinary site navigation when native links in a NavList are sufficient.

Features

• Supports controlled state, modal behavior, looping, and dismissal options.
• Opens from pointer or keyboard with the expected initial highlight.
• Includes actions, checkbox/radio choices, groups, separators, and submenus.
• Provides typeahead, focus restoration, collision-aware positioning, and RTL submenus.
• Registers portalled content with parent modal focus scopes.

Import

import { DropdownMenu } from "@flowstack-ui/atom";

Anatomy

<DropdownMenu.Root>
  <DropdownMenu.Trigger />
  <DropdownMenu.Content>
    <DropdownMenu.Group>
      <DropdownMenu.Item />
      <DropdownMenu.CheckboxItem />
      <DropdownMenu.RadioGroup>
        <DropdownMenu.RadioItem />
      </DropdownMenu.RadioGroup>
    </DropdownMenu.Group>
    <DropdownMenu.Separator />
    <DropdownMenu.Sub>
      <DropdownMenu.SubTrigger />
      <DropdownMenu.SubContent>
        <DropdownMenu.Item />
      </DropdownMenu.SubContent>
    </DropdownMenu.Sub>
  </DropdownMenu.Content>
</DropdownMenu.Root>

API Reference

Root

Owns shared menu state and renders no wrapper.

Trigger

Renders a native button by default. Pointer clicks toggle without an initial highlight; Enter, Space, and ArrowDown start at the first item, while ArrowUp starts at the last.

Content

Renders the portalled vertical menu, positions it against Trigger, manages highlight/typeahead, and restores focus on close.

Group

Renders a semantic group for related entries.

Item

Represents one command. textValue supplies typeahead text when children are not a plain string.

CheckboxItem

Represents an independent menu choice and stays open by default.

RadioGroup

Provides one controlled value to nested RadioItems.

RadioItem

Represents one mutually exclusive choice and stays open by default.

Separator

Creates a semantic horizontal boundary between entry groups.

Sub

Owns controlled or uncontrolled state for one nested menu and renders no DOM.

SubTrigger

Renders a menu item that opens SubContent by hover delay, click, or the direction-aware submenu key.

SubContent

Renders a separately portalled nested menu and mirrors placement and open/close keys in RTL.

The entry point also exports shared Menu context hooks for advanced custom parts. Prefer the namespaced parts for the complete behavior above.

Examples

Project Actions

import { DropdownMenu } from "@flowstack-ui/atom";

export function ProjectActions() {
  return (
    <DropdownMenu.Root>
      <DropdownMenu.Trigger>Actions</DropdownMenu.Trigger>
      <DropdownMenu.Content ariaLabel="Project actions">
        <DropdownMenu.Item value="duplicate" onSelect={() => console.log("Duplicate")}>
          Duplicate
        </DropdownMenu.Item>
        <DropdownMenu.Item value="archive" onSelect={() => console.log("Archive")}>
          Archive
        </DropdownMenu.Item>
      </DropdownMenu.Content>
    </DropdownMenu.Root>
  );
}

Persistent View Options

import { useState } from "react";
import { DropdownMenu } from "@flowstack-ui/atom";

export function ViewOptions() {
  const [grid, setGrid] = useState(true);
  return (
    <DropdownMenu.Root closeOnSelect={false}>
      <DropdownMenu.Trigger>View</DropdownMenu.Trigger>
      <DropdownMenu.Content ariaLabel="View options">
        <DropdownMenu.CheckboxItem value="grid" checked={grid} onCheckedChange={setGrid}>
          Show grid
        </DropdownMenu.CheckboxItem>
      </DropdownMenu.Content>
    </DropdownMenu.Root>
  );
}

Accessibility

DropdownMenu follows the WAI-ARIA Menu pattern. Trigger provides the menu popup relationship, Content owns focus, and disabled entries are skipped. Use visible Trigger text that describes the menu.

Changelog

See CHANGELOG.md.