overlayscontext-menu

ContextMenu

Menu triggered by right-click or long press on its child content.

Import#

import { ContextMenu } from 'moraine'

Slot Structure#

Right-click trigger with a floating menu portal containing grouped items.

Use contentProps and itemProps to forward native attributes, refs, and event handlers. Item handlers run before built-in menu behavior and can call preventDefault() to cancel activation.

trigger
└── content (portal)
    └── group (×n)
        ├── label (optional)
        ├── separator (optional)
        └── item (×n)

Item internals#

item
├── itemLeading (optional)
├── itemWrapper
│   ├── itemLabel (optional)
│   └── itemDescription (optional)
└── itemTrailing
    └── itemIndicator (optional, checkbox items)

Examples#

Sizes#

Menu item size scale from sm to lg for compact and roomy density.

1
function Sizes() {
2
  const SIZES = ['sm', 'md', 'lg'] as const
3

4
  const ITEMS: ContextMenuT.Item[] = [
5
    {
6
      type: 'group',
7
      children: [
8
        {
9
          label: 'Open',
10
          icon: 'i-lucide-folder-open',
11
        },
12
        {
13
          label: 'Rename',
14
          icon: 'i-lucide-pencil',
15
        },
16
        {
17
          label: 'Delete',
18
          icon: 'i-lucide-trash-2',
19
          color: 'destructive',
20
        },
21
      ],
22
    },
23
  ]
24

25
  return (
26
    <div class="flex flex-wrap gap-3">
27
      <For each={SIZES}>
28
        {(size) => (
29
          <ContextMenu size={size} items={ITEMS}>
30
            <Button variant="outline">Right click ({size})</Button>
31
          </ContextMenu>
32
        )}
33
      </For>
34
    </div>
35
  )
36
}

Placements#

Same file menu rendered with top/right/bottom/left placements for quick transition-direction sanity checks.

1
function Placements() {
2
  const surfaceClass =
3
    'flex h-24 w-full items-center justify-center rounded-lg b-1 b-border border-border bg-background text-sm text-foreground'
4

5
  const badgeClass =
6
    'rounded-md b-1 b-border border-border bg-muted px-1.5 py-0.5 font-medium text-[11px] text-foreground'
7

8
  const fileItems: ContextMenuT.Item[] = [
9
    {
10
      type: 'group',
11
      label: 'File Actions',
12
      children: [
13
        {
14
          label: 'Open File',
15
          icon: 'i-lucide-file-code-2',
16
          kbds: ['↵'],
17
        },
18
        {
19
          label: 'Open in Split View',
20
          icon: 'i-lucide-split-square-horizontal',
21
          kbds: ['⌘', '\\'],
22
        },
23
        {
24
          label: 'Reveal in Explorer',
25
          icon: 'i-lucide-folder-search-2',
26
        },
27
        { type: 'separator' },
28
        {
29
          label: 'Move To…',
30
          icon: 'i-lucide-folder-input',
31
          children: [
32
            {
33
              type: 'group',
34
              label: 'Recent Folders',
35
              children: [
36
                {
37
                  label: 'src/overlays',
38
                  icon: 'i-lucide-folder-open',
39
                },
40
                {
41
                  label: 'src/navigation',
42
                  icon: 'i-lucide-folder-open',
43
                },
44
                {
45
                  label: 'More Destinations',
46
                  icon: 'i-lucide-more-horizontal',
47
                  children: [
48
                    {
49
                      type: 'group',
50
                      children: [
51
                        {
52
                          label: 'docs/components',
53
                          icon: 'i-lucide-folder-open',
54
                        },
55
                        {
56
                          label: 'docs/content',
57
                          icon: 'i-lucide-folder-open',
58
                        },
59
                      ],
60
                    },
61
                  ],
62
                },
63
              ],
64
            },
65
          ],
66
        },
67
        {
68
          label: 'Copy Path',
69
          icon: 'i-lucide-copy',
70
          kbds: ['⌘', '⌥', 'C'],
71
        },
72
      ],
73
    },
74
    {
75
      type: 'group',
76
      children: [
77
        {
78
          label: (
79
            <div class="flex gap-2 items-center">
80
              <span>Rename</span>
81
              <span class={badgeClass}>F2</span>
82
            </div>
83
          ),
84
          icon: 'i-lucide-pencil',
85
        },
86
        {
87
          label: 'Delete',
88
          icon: 'i-lucide-trash-2',
89
          color: 'destructive',
90
        },
91
      ],
92
    },
93
  ]
94

95
  return (
96
    <div class="gap-3 grid sm:grid-cols-2">
97
      <ContextMenu placement="top" items={fileItems}>
98
        <div class={surfaceClass}>Right click (top)</div>
99
      </ContextMenu>
100
      <ContextMenu placement="right" items={fileItems}>
101
        <div class={surfaceClass}>Right click (right)</div>
102
      </ContextMenu>
103
      <ContextMenu placement="bottom" items={fileItems}>
104
        <div class={surfaceClass}>Right click (bottom)</div>
105
      </ContextMenu>
106
      <ContextMenu placement="left" items={fileItems}>
107
        <div class={surfaceClass}>Right click (left)</div>
108
      </ContextMenu>
109
    </div>
110
  )
111
}

File Explorer#

A file-row context menu with move flows, shortcuts, mixed labels, and destructive actions.

1
function FileExplorer() {
2
  const badgeClass =
3
    'rounded-md b-1 b-border border-border bg-muted px-1.5 py-0.5 font-medium text-[11px] text-foreground'
4

5
  const [lastAction, setLastAction] = createSignal('None')
6

7
  return (
8
    <div class="flex flex-col gap-4">
9
      <ContextMenu
10
        items={[
11
          {
12
            type: 'group',
13
            label: (
14
              <div class="flex gap-2 items-center">
15
                <span>Issue: Improve menu transitions</span>
16
                <span class={badgeClass}>P1</span>
17
              </div>
18
            ),
19
            children: [
20
              {
21
                label: 'Open Issue',
22
                icon: 'i-lucide-external-link',
23
                onSelect: () => setLastAction('Open issue'),
24
              },
25
              {
26
                label: 'Assign',
27
                icon: 'i-lucide-user-round-plus',
28
                children: [
29
                  {
30
                    type: 'group',
31
                    children: [
32
                      {
33
                        label: 'Alex Morgan',
34
                        description: 'Design systems',
35
                        icon: 'i-lucide-user',
36
                        onSelect: () => setLastAction('Assign Alex Morgan'),
37
                      },
38
                      {
39
                        label: 'Jamie Chen',
40
                        description: 'Overlay primitives',
41
                        icon: 'i-lucide-user',
42
                        onSelect: () => setLastAction('Assign Jamie Chen'),
43
                      },
44
                    ],
45
                  },
46
                ],
47
              },
48
              {
49
                label: 'Move to Sprint',
50
                icon: 'i-lucide-calendar-range',
51
                children: [
52
                  {
53
                    type: 'group',
54
                    children: [
55
                      {
56
                        label: 'Sprint 18',
57
                        onSelect: () => setLastAction('Move to Sprint 18'),
58
                      },
59
                      {
60
                        label: 'Sprint 19',
61
                        onSelect: () => setLastAction('Move to Sprint 19'),
62
                      },
63
                      {
64
                        label: 'Backlog',
65
                        onSelect: () => setLastAction('Move to backlog'),
66
                      },
67
                    ],
68
                  },
69
                ],
70
              },
71
            ],
72
          },
73
          {
74
            type: 'group',
75
            children: [
76
              {
77
                label: 'Edit Details',
78
                icon: 'i-lucide-pencil',
79
                onSelect: () => setLastAction('Edit details'),
80
              },
81
              {
82
                label: 'Share Update',
83
                icon: 'i-lucide-share-2',
84
                onSelect: () => setLastAction('Share update'),
85
              },
86
              { type: 'separator' },
87
              {
88
                label: 'Archive',
89
                icon: 'i-lucide-archive',
90
                onSelect: () => setLastAction('Archive issue'),
91
              },
92
              {
93
                label: 'Delete Issue',
94
                icon: 'i-lucide-trash-2',
95
                color: 'destructive',
96
                onSelect: () => setLastAction('Delete issue'),
97
              },
98
            ],
99
          },
100
        ]}
101
      >
102
        <div class="text-sm text-foreground p-4 b-1 b-border border-border rounded-lg bg-background flex flex-col min-h-28 w-full justify-between">
103
          <div class="flex gap-3 items-center justify-between">
104
            <div>
105
              <div class="text-foreground font-medium">dropdown-menu.tsx</div>
106
              <div class="text-xs text-muted-foreground">src/overlays/dropdown-menu</div>
107
            </div>
108
            <span class={badgeClass}>Modified</span>
109
          </div>
110
          <div class="text-xs text-muted-foreground">Right click this file row</div>
111
        </div>
112
      </ContextMenu>
113
      <p class="text-sm text-muted-foreground px-4">
114
        Last action: <span class="font-medium">{lastAction()}</span>
115
      </p>
116
    </div>
117
  )
118
}

Editor Selection#

A code-editor-style context menu with refactors, toggles, and theme switching for keyboard and pointer testing.

1
function EditorSelection() {
2
  const [showMinimap, setShowMinimap] = createSignal(true)
3
  const [showStickyScroll, setShowStickyScroll] = createSignal(true)
4
  const [showInlineHints, setShowInlineHints] = createSignal(false)
5
  const [editorTheme, setEditorTheme] = createSignal<'light' | 'dark' | 'system'>('dark')
6

7
  const editorItems = createMemo<ContextMenuT.Item[]>(() => [
8
    {
9
      type: 'group',
10
      label: 'Editor Selection',
11
      children: [
12
        {
13
          label: 'Quick Fix…',
14
          icon: 'i-lucide-wand-sparkles',
15
          kbds: ['⌘', '.'],
16
        },
17
        {
18
          label: 'Refactor',
19
          icon: 'i-lucide-git-branch-plus',
20
          children: [
21
            {
22
              type: 'group',
23
              children: [
24
                {
25
                  label: 'Extract Variable',
26
                  icon: 'i-lucide-variable',
27
                },
28
                {
29
                  label: 'Extract Function',
30
                  icon: 'i-lucide-braces',
31
                },
32
                {
33
                  label: 'Move to File…',
34
                  icon: 'i-lucide-file-output',
35
                },
36
              ],
37
            },
38
          ],
39
        },
40
        { type: 'separator' },
41
        {
42
          type: 'checkbox',
43
          label: 'Show Minimap',
44
          icon: 'i-lucide-map',
45
          checked: showMinimap(),
46
          onCheckedChange: (checked: boolean) => setShowMinimap(checked),
47
        },
48
        {
49
          type: 'checkbox',
50
          label: 'Sticky Scroll',
51
          icon: 'i-lucide-panel-top',
52
          checked: showStickyScroll(),
53
          onCheckedChange: (checked: boolean) => setShowStickyScroll(checked),
54
        },
55
        {
56
          type: 'checkbox',
57
          label: 'Inline Hints',
58
          icon: 'i-lucide-message-square-quote',
59
          checked: showInlineHints(),
60
          onCheckedChange: (checked: boolean) => setShowInlineHints(checked),
61
        },
62
      ],
63
    },
64
    {
65
      type: 'group',
66
      label: 'Theme',
67
      children: [
68
        {
69
          label: 'Light',
70
          icon: editorTheme() === 'light' ? 'i-lucide-check' : 'i-lucide-sun',
71
          onSelect: () => setEditorTheme('light'),
72
        },
73
        {
74
          label: 'Dark',
75
          icon: editorTheme() === 'dark' ? 'i-lucide-check' : 'i-lucide-moon',
76
          onSelect: () => setEditorTheme('dark'),
77
        },
78
        {
79
          label: 'System',
80
          icon: editorTheme() === 'system' ? 'i-lucide-check' : 'i-lucide-monitor',
81
          onSelect: () => setEditorTheme('system'),
82
        },
83
      ],
84
    },
85
  ])
86

87
  return (
88
    <div class="flex flex-col">
89
      <ContextMenu items={editorItems()}>
90
        <div class="text-sm text-foreground p-4 b-1 b-border border-border rounded-lg bg-background flex flex-col min-h-28 w-full justify-between">
91
          <div class="text-xs text-foreground font-mono">
92
            const motion = resolveOverlayMenuSide(placement)
93
          </div>
94
          <div class="text-xs text-muted-foreground">Right click the selected line</div>
95
        </div>
96
      </ContextMenu>
97
      <div class="text-sm text-muted-foreground mt-3 flex flex-wrap gap-4">
98
        <span>
99
          Minimap: <span class="font-medium">{String(showMinimap())}</span>
100
        </span>
101
        <span>
102
          Sticky scroll: <span class="font-medium">{String(showStickyScroll())}</span>
103
        </span>
104
        <span>
105
          Inline hints: <span class="font-medium">{String(showInlineHints())}</span>
106
        </span>
107
        <span>
108
          Theme: <span class="font-medium uppercase">{editorTheme()}</span>
109
        </span>
110
      </div>
111
    </div>
112
  )
113
}

Project / Issue Actions#

A denser project card menu with assignee and sprint submenus plus archive/delete actions.

1
function ProjectIssueActions() {
2
  const panelClass =
3
    'flex min-h-28 w-full flex-col justify-between rounded-lg b-1 b-border border-border bg-background p-4 text-sm text-foreground'
4

5
  const projectItems: ContextMenuT.Item[] = [
6
    {
7
      type: 'group',
8
      label: (
9
        <div class="flex gap-2 items-center">
10
          <span>Issue: Improve menu transitions</span>
11
          <span class={badgeClass}>P1</span>
12
        </div>
13
      ),
14
      children: [
15
        {
16
          label: 'Open Issue',
17
          icon: 'i-lucide-external-link',
18
        },
19

20
        {
21
          label: 'Move to Sprint',
22
          icon: 'i-lucide-calendar-range',
23
          children: [
24
            {
25
              type: 'group',
26
              children: [
27
                {
28
                  label: 'Sprint 18',
29
                },
30
                {
31
                  label: 'Sprint 19',
32
                },
33
                {
34
                  label: 'Sprint 20',
35
                },
36
                {
37
                  label: 'Sprint 21',
38
                },
39
                {
40
                  label: 'Sprint 22',
41
                },
42
                {
43
                  label: 'Backlog',
44
                },
45
              ],
46
            },
47
          ],
48
        },
49
        {
50
          label: 'Edit Details',
51
          icon: 'i-lucide-pencil',
52
        },
53
        {
54
          label: 'Assign',
55
          icon: 'i-lucide-user-round-plus',
56
          children: [
57
            {
58
              type: 'group',
59
              children: [
60
                {
61
                  label: 'Alex Morgan',
62
                  description: 'Design systems',
63
                  icon: 'i-lucide-user',
64
                },
65
                {
66
                  label: 'Jamie Chen',
67
                  description: 'Overlay primitives',
68
                  icon: 'i-lucide-user',
69
                },
70
                {
71
                  label: 'John Smith',
72
                  description: 'Test',
73
                  icon: 'i-lucide-circle',
74
                },
75
              ],
76
            },
77
          ],
78
        },
79
        {
80
          label: 'Share Update',
81
          icon: 'i-lucide-share-2',
82
        },
83
        { type: 'separator' },
84
        {
85
          label: 'Archive',
86
          icon: 'i-lucide-archive',
87
        },
88
        {
89
          label: 'Delete Issue',
90
          icon: 'i-lucide-trash-2',
91
          color: 'destructive',
92
        },
93
      ],
94
    },
95
  ]
96

97
  return (
98
    <ContextMenu items={projectItems}>
99
      <div class={panelClass}>
100
        <div class="flex gap-3 items-center justify-between">
101
          <div>
102
            <div class="text-foreground font-medium">
103
              Improve dropdown/context menu motion polish
104
            </div>
105
            <div class="text-xs text-muted-foreground">Overlay milestone · due this sprint</div>
106
          </div>
107
          <span class={badgeClass}>In Review</span>
108
        </div>
109
        <div class="text-xs text-muted-foreground">Right click this card</div>
110
      </div>
111
    </ContextMenu>
112
  )
113
}

API Reference#

Attributes#

Slottrigger6 attributes

Element users activate to open the menu.

Data Attributes

Data Attribute	Description
data-closed	State or slot attribute exposed for styling hooks and selectors.
data-disabled	Present when the component or item is disabled.
data-expanded	State or slot attribute exposed for styling hooks and selectors.

ARIA Attributes

ARIA Attribute	Description
aria-controls	References the controlled element while the related content is mounted.
aria-expanded	Indicates whether the controlled content is expanded.
aria-haspopup	Accessibility attribute forwarded by the rendered component.

Props#

Prop	Type	Default	Description
checkedIcon	`IconT.Name`	`icon-check`	Icon used for checked checkbox items.
children	`JSX.Element`	—	Target area that opens the context menu on right-click or long press.
class	`ClassValue`	—	Class applied to the component root or trigger element.
classes	`(OverlayMenuSharedClasses & ContextMenuT.Classes) \| undefined`	—	Slot class overrides for menu sections.
contentBottom	`OverlayMenuContentSlot \| undefined`	—	Content rendered after the resolved item groups.
contentProps	`ElementProps<HTMLDivElement> \| undefined`	—	Additional attributes for each menu layer content element.
contentTop	`OverlayMenuContentSlot \| undefined`	—	Content rendered before the resolved item groups.
defaultOpen	`boolean \| undefined`	`false`	Initial open state when the component is uncontrolled.
disabled	`boolean \| undefined`	`false`	Whether trigger interactions should be ignored.
gutter	`number \| undefined`	`0`	Gap between the anchor and the content.
id	`string \| undefined`	—	Unique base id used to derive trigger and content ids.
itemProps	`((props: ContextMenuT.ItemRenderProps) => ElementProps<HTMLDivElement> \| undefined) \| undefined`	—	Additional attributes for an interactive menu item.
itemRender	`ComponentOrElement<ContextMenuT.ItemRenderProps> \| undefined`	—	Custom renderer for individual items.
items	`ContextMenuT.Item[] \| undefined`	—	Items rendered in the menu body.
onContextMenu	`JSX.EventHandlerUnion<HTMLSpanElement, MouseEvent> \| undefined`	—	—
onKeyDown	`JSX.EventHandlerUnion<HTMLSpanElement, KeyboardEvent> \| undefined`	—	—
onOpenChange	`((open: boolean) => void) \| undefined`	—	Called whenever the menu requests an open state change.
onPointerCancel	`JSX.EventHandlerUnion<HTMLSpanElement, PointerEvent> \| undefined`	—	—
onPointerDown	`JSX.EventHandlerUnion<HTMLSpanElement, PointerEvent> \| undefined`	—	—
onPointerMove	`JSX.EventHandlerUnion<HTMLSpanElement, PointerEvent> \| undefined`	—	—
onPointerUp	`JSX.EventHandlerUnion<HTMLSpanElement, PointerEvent> \| undefined`	—	—
open	`boolean \| undefined`	—	Controlled open state of the menu.
overflowPadding	`number \| undefined`	`4`	Padding applied to the overflow area when calculating the menu's position.
placement	`OverlayMenuPlacement \| undefined`	—	Preferred content placement relative to the trigger or anchor point.
preventScroll	`boolean \| undefined`	`true`	Whether body scroll should be locked while the menu is open.
ref	`JSX.HTMLElementTags["span"] extends { ref?: infer Ref; } ? Ref : never \| undefined`	—	—
size	`"sm" \| "md" \| "lg" \| undefined`	`md`	Menu item size variant.
style	`JSX.CSSProperties \| undefined`	—	—
styles	`(OverlayMenuSharedStyles & ContextMenuT.Styles) \| undefined`	—	Slot style overrides for menu sections.
submenuIcon	`IconT.Name`	`icon-chevron-right`	Icon used for submenu trigger items.

Items#

Prop	Type	Default	Description
checked	`boolean \| undefined`	—	Controlled checked state for checkbox and radio items.
children	`ContextMenuT.Item[] \| undefined`	—	Nested menu items for creating submenus.
color	`NonNullable<"default" \| "destructive" \| undefined> \| undefined`	—	Color theme variant for the menu item.
defaultChecked	`boolean \| undefined`	—	Initial checked state for uncontrolled checkbox and radio items.
defaultOpen	`boolean \| undefined`	—	Initial open state for submenus.
description	`JSX.Element`	—	Secondary description text displayed below the label.
disabled	`boolean \| undefined`	`false`	Whether the item is non-interactive.
group	`string \| undefined`	—	Radio group identifier. Radio items with the same group are mutually exclusive.
icon	`IconT.Name`	—	Icon name or custom element to display at the start of the item.
kbds	`string[] \| undefined`	—	Array of keyboard shortcuts to display as keys.
label	`JSX.Element`	—	Primary label text or element.
onCheckedChange	`((checked: boolean) => void) \| undefined`	—	Event handler called when a checkbox item's state changes.
onSelect	`(() => void) \| undefined`	—	Event handler called when the item is activated.
onValueChange	`((value: string) => void) \| undefined`	—	Event handler called when a radio item is selected.
open	`boolean \| undefined`	—	Controlled open state for submenus.
type	`OverlayMenuItemType \| undefined`	`item`	The type of menu item to render.
value	`string \| undefined`	—	Radio item value reported by onValueChange and used for grouped selection.