Context Menu

Quick Implementation

1. Wrap the interactive area with ContextMenu.Root.
2. Use ContextMenu.Trigger as the right-click surface.
3. Render menu content inside Portal → Positioner → Popup.
4. Add actions with Item, CheckboxItem, RadioItem, or SubmenuRoot.
5. Keep visual consistency with theme tokens: bg-card, bg-popover, border-border, text-foreground, text-muted-foreground, bg-accent.

import { ContextMenu } from 'gnome-ui/context-menu';
import { Copy, Trash2 } from 'lucide-react';

export function ContextMenuBasic() {
  return (
    <ContextMenu.Root>
      <ContextMenu.Trigger className="block rounded-lg border border-border bg-background px-5 py-8 text-center text-sm text-muted-foreground hover:bg-accent/50">
        Right click here
      </ContextMenu.Trigger>

      <ContextMenu.Portal>
        <ContextMenu.Positioner sideOffset={8} className="z-50 outline-none">
          <ContextMenu.Popup className="z-50 min-w-[220px] rounded-xl border border-border bg-popover p-1 text-popover-foreground shadow-md">
            <ContextMenu.Item className="flex items-center gap-2 rounded-md px-2 py-1.5 text-sm data-[highlighted]:bg-accent data-[highlighted]:text-accent-foreground">
              <Copy className="size-4 text-muted-foreground" />
              Copy
            </ContextMenu.Item>
            <ContextMenu.Separator className="mx-1 my-1 h-px bg-border" />
            <ContextMenu.Item className="flex items-center gap-2 rounded-md px-2 py-1.5 text-sm text-destructive data-[highlighted]:bg-destructive/10 data-[highlighted]:text-destructive">
              <Trash2 className="size-4" />
              Delete
            </ContextMenu.Item>
          </ContextMenu.Popup>
        </ContextMenu.Positioner>
      </ContextMenu.Portal>
    </ContextMenu.Root>
  );
}

Anatomy

import { ContextMenu } from 'gnome-ui/context-menu';

<ContextMenu.Root>
  <ContextMenu.Trigger />
  <ContextMenu.Portal>
    <ContextMenu.Positioner>
      <ContextMenu.Popup>
        <ContextMenu.Item />
      </ContextMenu.Popup>
    </ContextMenu.Positioner>
  </ContextMenu.Portal>
</ContextMenu.Root>

Examples

View Options (checkbox + radio)

Ideal for file-manager style views where you need quick toggles and sorting options.

import { ContextMenu } from 'gnome-ui/context-menu';
import { Check } from 'lucide-react';

export function ContextMenuViewOptions() {
  return (
    <ContextMenu.Root>
      <ContextMenu.Trigger className="block rounded-lg border border-border bg-background px-5 py-8 text-center text-sm text-muted-foreground hover:bg-accent/50">
        Right click to configure view options
      </ContextMenu.Trigger>

      <ContextMenu.Portal>
        <ContextMenu.Positioner sideOffset={8} className="z-50 outline-none">
          <ContextMenu.Popup className="z-50 min-w-[220px] rounded-xl border border-border bg-popover p-1 text-popover-foreground shadow-md">
            <ContextMenu.Group>
              <ContextMenu.GroupLabel className="px-2 py-1 text-xs font-semibold uppercase tracking-wider text-muted-foreground">
                Visibility
              </ContextMenu.GroupLabel>

              <ContextMenu.CheckboxItem className="flex items-center gap-2 rounded-md px-2 py-1.5 text-sm data-[highlighted]:bg-accent data-[highlighted]:text-accent-foreground" defaultChecked>
                <ContextMenu.CheckboxItemIndicator className="flex size-4 items-center justify-center">
                  <Check className="size-3.5 text-primary" />
                </ContextMenu.CheckboxItemIndicator>
                Show hidden files
              </ContextMenu.CheckboxItem>
            </ContextMenu.Group>

            <ContextMenu.Separator className="mx-1 my-1 h-px bg-border" />

            <ContextMenu.RadioGroup defaultValue="name">
              <ContextMenu.RadioItem value="name" className="flex items-center gap-2 rounded-md px-2 py-1.5 text-sm data-[highlighted]:bg-accent data-[highlighted]:text-accent-foreground">
                <ContextMenu.RadioItemIndicator className="flex size-4 items-center justify-center">
                  <div className="size-2 rounded-full bg-primary" />
                </ContextMenu.RadioItemIndicator>
                Name
              </ContextMenu.RadioItem>
            </ContextMenu.RadioGroup>
          </ContextMenu.Popup>
        </ContextMenu.Positioner>
      </ContextMenu.Portal>
    </ContextMenu.Root>
  );
}

Submenu Actions

Perfect for keeping the main menu clean when secondary actions (like sharing) are needed.

import { ContextMenu } from 'gnome-ui/context-menu';
import { ChevronRight, Share2 } from 'lucide-react';

export function ContextMenuSubmenu() {
  return (
    <ContextMenu.Root>
      <ContextMenu.Trigger className="block rounded-lg border border-border bg-background px-5 py-8 text-center text-sm text-muted-foreground hover:bg-accent/50">
        Right click to open actions with submenu
      </ContextMenu.Trigger>

      <ContextMenu.Portal>
        <ContextMenu.Positioner sideOffset={8} className="z-50 outline-none">
          <ContextMenu.Popup className="z-50 min-w-[220px] rounded-xl border border-border bg-popover p-1 text-popover-foreground shadow-md">
            <ContextMenu.SubmenuRoot>
              <ContextMenu.SubmenuTrigger className="flex items-center justify-between rounded-md px-2 py-1.5 text-sm data-[highlighted]:bg-accent data-[highlighted]:text-accent-foreground">
                <span className="inline-flex items-center gap-2">
                  <Share2 className="size-4 text-muted-foreground" />
                  Share
                </span>
                <ChevronRight className="size-4 text-muted-foreground" />
              </ContextMenu.SubmenuTrigger>

              <ContextMenu.Portal>
                <ContextMenu.Positioner sideOffset={6} alignOffset={-4} className="z-50 outline-none">
                  <ContextMenu.Popup className="z-50 min-w-[220px] rounded-xl border border-border bg-popover p-1 text-popover-foreground shadow-md">
                    <ContextMenu.Item className="rounded-md px-2 py-1.5 text-sm data-[highlighted]:bg-accent data-[highlighted]:text-accent-foreground">
                      Copy link
                    </ContextMenu.Item>
                  </ContextMenu.Popup>
                </ContextMenu.Positioner>
              </ContextMenu.Portal>
            </ContextMenu.SubmenuRoot>
          </ContextMenu.Popup>
        </ContextMenu.Positioner>
      </ContextMenu.Portal>
    </ContextMenu.Root>
  );
}

API reference

Root

A component that creates a context menu activated by right clicking or long pressing. Doesn’t render its own HTML element.

Root Props:

Trigger

An area that opens the menu on right click or long press. Renders a <div> element.

Trigger Props:

Trigger Data Attributes:

Portal

A portal element that moves the popup to a different part of the DOM. By default, the portal element is appended to <body>. Renders a <div> element.

Portal Props:

Positioner

Positions the menu popup against the trigger. Renders a <div> element.

Positioner Props:

• data.positioner: the dimensions of the positioner element with properties width and height.
• data.side: which side of the anchor element the positioner is aligned against.
• data.align: how the positioner is aligned relative to the specified side. | | side | Side | 'bottom' | Which side of the anchor element to align the popup against. May automatically change to avoid collisions. | | sideOffset | number \| OffsetFunction | 0 | Distance between the anchor and the popup in pixels. Also accepts a function that returns the distance to read the dimensions of the anchor and positioner elements, along with its side and alignment.The function takes a data object parameter with the following properties:* data.anchor: the dimensions of the anchor element with properties width and height.
• data.positioner: the dimensions of the positioner element with properties width and height.
• data.side: which side of the anchor element the positioner is aligned against.
• data.align: how the positioner is aligned relative to the specified side. | | arrowPadding | number | 5 | Minimum distance to maintain between the arrow and the edges of the popup.Use it to prevent the arrow element from hanging out of the rounded corners of a popup. | | anchor | Element \| VirtualElement \| RefObject<Element \| null> \| (() => Element \| VirtualElement \| null) \| null | - | An element to position the popup against. By default, the popup will be positioned against the trigger. | | collisionAvoidance | CollisionAvoidance | - | Determines how to handle collisions when positioning the popup. | | collisionBoundary | Boundary | 'clipping-ancestors' | An element or a rectangle that delimits the area that the popup is confined to. | | collisionPadding | Padding | 5 | Additional space to maintain from the edge of the collision boundary. | | sticky | boolean | false | Whether to maintain the popup in the viewport after the anchor element was scrolled out of view. | | positionMethod | 'absolute' \| 'fixed' | 'absolute' | Determines which CSS position property to use. | | className | string \| ((state: Menu.Positioner.State) => string \| undefined) | - | CSS class applied to the element, or a function that returns a class based on the component’s state. | | style | CSSProperties \| ((state: Menu.Positioner.State) => CSSProperties \| undefined) | - | - | | render | ReactElement \| ((props: HTMLProps, state: Menu.Positioner.State) => ReactElement) | - | Allows you to replace the component’s HTML element with a different tag, or compose it with another component.Accepts a ReactElement or a function that returns the element to render. |

Positioner Data Attributes:

Positioner CSS Variables:

Popup

A container for the menu items. Renders a <div> element.

Popup Props:

• true: Move focus based on the default behavior (trigger or previously focused element).
• RefObject: Move focus to the ref element.
• function: Called with the interaction type (mouse, touch, pen, or keyboard). Return an element to focus, true to use the default behavior, or false/undefined to do nothing. | | children | ReactNode | - | - | | className | string \| ((state: Menu.Popup.State) => string \| undefined) | - | CSS class applied to the element, or a function that returns a class based on the component’s state. | | style | CSSProperties \| ((state: Menu.Popup.State) => CSSProperties \| undefined) | - | * | | render | ReactElement \| ((props: HTMLProps, state: Menu.Popup.State) => ReactElement) | - | Allows you to replace the component’s HTML element with a different tag, or compose it with another component.Accepts a ReactElement or a function that returns the element to render. |

Popup Data Attributes:

Arrow

Displays an element positioned against the menu anchor. Renders a <div> element.

Arrow Props:

Arrow Data Attributes:

Item

An individual interactive item in the menu. Renders a <div> element.

Item Props:

Item Data Attributes:

LinkItem

A link in the menu that can be used to navigate to a different page or section. Renders an <a> element.

LinkItem Props:

LinkItem Data Attributes:

SubmenuRoot

Groups all parts of a submenu. Doesn’t render its own HTML element.

SubmenuRoot Props:

SubmenuTrigger

A menu item that opens a submenu. Renders a <div> element.

SubmenuTrigger Props:

SubmenuTrigger Data Attributes:

Group

Groups related menu items with the corresponding label. Renders a <div> element.

Group Props:

GroupLabel

An accessible label that is automatically associated with its parent group. Renders a <div> element.

GroupLabel Props:

RadioGroup

Groups related radio items. Renders a <div> element.

RadioGroup Props:

RadioItem

A menu item that works like a radio button in a given group. Renders a <div> element.

RadioItem Props:

RadioItem Data Attributes:

RadioItemIndicator

Indicates whether the radio item is selected. Renders a <span> element.

RadioItemIndicator Props:

RadioItemIndicator Data Attributes:

CheckboxItem

A menu item that toggles a setting on or off. Renders a <div> element.

CheckboxItem Props:

CheckboxItem Data Attributes:

CheckboxItemIndicator

Indicates whether the checkbox item is ticked. Renders a <span> element.

CheckboxItemIndicator Props:

CheckboxItemIndicator Data Attributes:

Separator

A separator element accessible to screen readers. Renders a <div> element.

Separator Props: