Components

ContextMenu

Headless menu primitives that open at a pointer location or from the keyboard to present actions for a specific area.

When to Use

Use ContextMenu when actions belong to the exact thing a user right-clicked, such as a file, canvas object, or table row. Do not make it the only way to reach important actions because context menus are easy to miss. Use Menu or DropdownMenu when a visible button should open the actions, and Menubar for a persistent application command bar.

Features

• Opens at right-click coordinates or the keyboard trigger location.
• Supports controlled state, modal behavior, looping, and dismissal settings.
• Includes actions, checkbox choices, radio choices, groups, separators, and nested menus.
• Positions and collision-adjusts Content with Floating UI.
• Supports pointer highlight, keyboard navigation, typeahead, and RTL submenus.
• Keeps nested portalled menus inside parent modal focus scopes.

Import

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

Anatomy

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

API Reference

Root

Owns Menu state and the point used to position Content. It renders no wrapper.

Trigger

Wraps the area that owns the menu. It renders a span with display: contents by default, opens on the context-menu gesture, and does not add button semantics to the wrapped area.

Content

Renders the portalled menu at Trigger's pointer or keyboard anchor, manages focus and highlight, locks scrolling when modal, and closes on outside click.

Group

Groups related menu entries as a div. Provide a native accessible label when the grouping needs to be announced.

Item

Represents one command. Its unique value supports highlight and typeahead; textValue supplies searchable text when children are not plain text.

CheckboxItem

Represents an independently toggleable menu choice. It stays open by default so several choices can be changed in one visit.

RadioGroup

Shares one controlled value with nested RadioItems and renders a semantic group.

RadioItem

Represents one mutually exclusive value inside RadioGroup. Selection does not close the menu unless closeOnSelect is enabled.

Separator

Marks a horizontal boundary between related groups of commands.

Sub

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

SubTrigger

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

SubContent

Renders a separately portalled nested menu, positions it beside SubTrigger, and mirrors its side and open/close keys in RTL.

The package also exports useContextMenuContext for advanced custom parts. It returns the current anchor point and its setter and must be used within Root.

Examples

File Actions

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

export function FileContextMenu() {
  return (
    <ContextMenu.Root>
      <ContextMenu.Trigger>
        <article tabIndex={0}>Quarterly report.pdf</article>
      </ContextMenu.Trigger>
      <ContextMenu.Content ariaLabel="File actions">
        <ContextMenu.Item value="open" onSelect={() => console.log("Open")}>
          Open
        </ContextMenu.Item>
        <ContextMenu.Item value="rename" onSelect={() => console.log("Rename")}>
          Rename
        </ContextMenu.Item>
        <ContextMenu.Separator />
        <ContextMenu.Item value="delete" onSelect={() => console.log("Delete")}>
          Delete
        </ContextMenu.Item>
      </ContextMenu.Content>
    </ContextMenu.Root>
  );
}

Persistent View Choices

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

export function CanvasContextMenu() {
  const [snap, setSnap] = useState(true);
  const [density, setDensity] = useState("comfortable");

  return (
    <ContextMenu.Root closeOnSelect={false}>
      <ContextMenu.Trigger>
        <section tabIndex={0}>Canvas</section>
      </ContextMenu.Trigger>
      <ContextMenu.Content ariaLabel="View options">
        <ContextMenu.CheckboxItem
          value="snap"
          checked={snap}
          onCheckedChange={setSnap}
        >
          Snap to grid
        </ContextMenu.CheckboxItem>
        <ContextMenu.RadioGroup value={density} onValueChange={setDensity}>
          <ContextMenu.RadioItem value="compact">Compact</ContextMenu.RadioItem>
          <ContextMenu.RadioItem value="comfortable">Comfortable</ContextMenu.RadioItem>
        </ContextMenu.RadioGroup>
      </ContextMenu.Content>
    </ContextMenu.Root>
  );
}

Accessibility

ContextMenu follows the WAI-ARIA Menu pattern. Trigger supports the platform context-menu gestures, while Content owns focus, highlight, and menu navigation. Keep important actions available through a visible control as well.

Changelog

See CHANGELOG.md.