overlaysdropdown-menu

DropdownMenu

Triggered action menu anchored to its child content.

Import#

import { DropdownMenu } from 'moraine'

Slot Structure#

Wrapper 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: DropdownMenuT.Item[] = [
5
    {
6
      type: 'group',
7
      children: [
8
        {
9
          label: 'Profile',
10
          icon: 'i-lucide-user',
11
        },
12
        {
13
          label: 'Settings',
14
          icon: 'i-lucide-settings-2',
15
        },
16
        {
17
          label: 'Sign Out',
18
          icon: 'i-lucide-log-out',
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
          <DropdownMenu size={size} items={ITEMS}>
30
            <Button variant="outline" size="sm">
31
              {size} Menu
32
            </Button>
33
          </DropdownMenu>
34
        )}
35
      </For>
36
    </div>
37
  )
38
}

Account / Team#

An account dropdown with grouped actions, workspace switching, shortcut hints, and a destructive sign-out row.

1
function AccountTeam() {
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 avatarClass =
6
    'grid size-4 place-items-center rounded-full bg-linear-to-br from-primary to-accent text-[10px] font-semibold text-primary-foreground'
7

8
  const [lastAction, setLastAction] = createSignal('None')
9

10
  return (
11
    <div class="flex flex-col gap-3 sm:flex-row sm:items-center sm:justify-between">
12
      <DropdownMenu
13
        items={[
14
          {
15
            type: 'group',
16
            label: 'Account',
17
            children: [
18
              {
19
                label: (
20
                  <div class="flex gap-2 items-center">
21
                    <span class="font-medium">Alex Morgan</span>
22
                    <span class={badgeClass}>Owner</span>
23
                  </div>
24
                ),
25
                description: '[email protected]',
26
                icon: <span class={avatarClass}>AM</span>,
27
                onSelect: () => setLastAction('Open account profile'),
28
              },
29
              { type: 'separator' },
30
              {
31
                label: 'Switch Workspace',
32
                icon: 'i-lucide-building-2',
33
                children: [
34
                  {
35
                    type: 'group',
36
                    label: 'Recent Workspaces',
37
                    children: [
38
                      {
39
                        label: 'Design System',
40
                        description: '12 teammates · shared tokens',
41
                        icon: 'i-lucide-palette',
42
                        onSelect: () => setLastAction('Switch to Design System'),
43
                      },
44
                      {
45
                        label: 'Platform Ops',
46
                        description: '8 teammates · deploy tooling',
47
                        icon: 'i-lucide-server',
48
                        onSelect: () => setLastAction('Switch to Platform Ops'),
49
                      },
50
                      {
51
                        label: 'Support Workspace',
52
                        description: '5 teammates · customer issues',
53
                        icon: 'i-lucide-life-buoy',
54
                        onSelect: () => setLastAction('Switch to Support Workspace'),
55
                      },
56
                    ],
57
                  },
58
                  {
59
                    type: 'group',
60
                    label: 'Actions',
61
                    children: [
62
                      {
63
                        label: 'Create Workspace',
64
                        icon: 'i-lucide-plus',
65
                        onSelect: () => setLastAction('Create workspace'),
66
                      },
67
                    ],
68
                  },
69
                ],
70
              },
71
              {
72
                label: 'Invite Teammates',
73
                icon: 'i-lucide-user-plus',
74
                kbds: ['⌘', 'I'],
75
                onSelect: () => setLastAction('Invite teammates'),
76
              },
77
              {
78
                label: 'Billing & Usage',
79
                icon: 'i-lucide-credit-card',
80
                onSelect: () => setLastAction('Billing & usage'),
81
              },
82
            ],
83
          },
84
          {
85
            type: 'group',
86
            label: 'Preferences',
87
            children: [
88
              {
89
                label: 'Account Settings',
90
                icon: 'i-lucide-settings-2',
91
                kbds: ['⌘', ','],
92
                onSelect: () => setLastAction('Account settings'),
93
              },
94
              {
95
                label: 'Keyboard Shortcuts',
96
                icon: 'i-lucide-command',
97
                kbds: ['⌘', 'K'],
98
                onSelect: () => setLastAction('Keyboard shortcuts'),
99
              },
100
              {
101
                label: 'Support Inbox',
102
                icon: 'i-lucide-life-buoy',
103
                onSelect: () => setLastAction('Support inbox'),
104
              },
105
            ],
106
          },
107
          {
108
            type: 'group',
109
            children: [
110
              {
111
                label: 'Sign Out',
112
                icon: 'i-lucide-log-out',
113
                color: 'destructive',
114
                onSelect: () => setLastAction('Sign out'),
115
              },
116
            ],
117
          },
118
        ]}
119
      >
120
        <Button variant="outline">Open account menu</Button>
121
      </DropdownMenu>
122
      <p class="text-sm text-muted-foreground">
123
        Last action: <span class="font-medium">{lastAction()}</span>
124
      </p>
125
    </div>
126
  )
127
}

Editor / View Options#

A workspace-style menu with recent files, nested submenus, checkbox toggles, and theme selection for keyboard and pointer testing.

1
function EditorViewOptions() {
2
  const [showLineNumbers, setShowLineNumbers] = createSignal(true)
3
  const [showMinimap, setShowMinimap] = createSignal(true)
4
  const [previewTabs, setPreviewTabs] = createSignal(false)
5
  const [autoSave, setAutoSave] = createSignal(true)
6
  const [theme, setTheme] = createSignal<'light' | 'dark' | 'system'>('dark')
7

8
  const editorItems = createMemo<DropdownMenuT.Item[]>(() => [
9
    {
10
      type: 'group',
11
      label: 'Editor',
12
      children: [
13
        {
14
          label: 'Command Palette',
15
          description: 'Jump to commands, files, and symbols',
16
          icon: 'i-lucide-search',
17
          kbds: ['⌘', 'K'],
18
        },
19
        {
20
          label: 'Go to File…',
21
          icon: 'i-lucide-file-search',
22
          kbds: ['⌘', 'P'],
23
        },
24
        {
25
          label: 'Open Recent',
26
          icon: 'i-lucide-history',
27
          children: [
28
            {
29
              type: 'group',
30
              label: 'Recent Files',
31
              children: [
32
                {
33
                  label: 'src/overlays/dropdown-menu/dropdown-menu.tsx',
34
                  icon: 'i-lucide-file-code-2',
35
                },
36
                {
37
                  label: 'docs/components/context-menu-demos.tsx',
38
                  icon: 'i-lucide-file-code-2',
39
                },
40
                {
41
                  label: 'Pinned Workspaces',
42
                  icon: 'i-lucide-star',
43
                  children: [
44
                    {
45
                      type: 'group',
46
                      children: [
47
                        {
48
                          label: 'Moraine',
49
                          description: 'packages + docs',
50
                          icon: 'i-lucide-folder-kanban',
51
                        },
52
                        {
53
                          label: 'Docs Site',
54
                          description: 'marketing + guides',
55
                          icon: 'i-lucide-book-open',
56
                        },
57
                      ],
58
                    },
59
                  ],
60
                },
61
              ],
62
            },
63
          ],
64
        },
65
      ],
66
    },
67
    {
68
      type: 'group',
69
      label: 'View',
70
      children: [
71
        {
72
          type: 'checkbox',
73
          label: 'Line Numbers',
74
          icon: 'i-lucide-list',
75
          checked: showLineNumbers(),
76
          onCheckedChange: (checked: boolean) => setShowLineNumbers(checked),
77
        },
78
        {
79
          type: 'checkbox',
80
          label: 'Minimap',
81
          icon: 'i-lucide-map',
82
          checked: showMinimap(),
83
          onCheckedChange: (checked: boolean) => setShowMinimap(checked),
84
        },
85
        {
86
          type: 'checkbox',
87
          label: 'Preview Tabs',
88
          icon: 'i-lucide-panel-top',
89
          checked: previewTabs(),
90
          onCheckedChange: (checked: boolean) => setPreviewTabs(checked),
91
        },
92
        {
93
          type: 'checkbox',
94
          label: 'Auto Save',
95
          icon: 'i-lucide-save',
96
          checked: autoSave(),
97
          onCheckedChange: (checked: boolean) => setAutoSave(checked),
98
        },
99
        { type: 'separator' },
100
        {
101
          label: 'Theme',
102
          icon: 'i-lucide-palette',
103
          children: [
104
            {
105
              type: 'group',
106
              label: 'Appearance',
107
              children: [
108
                {
109
                  label: 'Light',
110
                  icon: theme() === 'light' ? 'i-lucide-check' : 'i-lucide-sun',
111
                  onSelect: () => setTheme('light'),
112
                },
113
                {
114
                  label: 'Dark',
115
                  icon: theme() === 'dark' ? 'i-lucide-check' : 'i-lucide-moon',
116
                  onSelect: () => setTheme('dark'),
117
                },
118
                {
119
                  label: 'System',
120
                  icon: theme() === 'system' ? 'i-lucide-check' : 'i-lucide-monitor',
121
                  onSelect: () => setTheme('system'),
122
                },
123
              ],
124
            },
125
          ],
126
        },
127
      ],
128
    },
129
    {
130
      type: 'group',
131
      label: 'Panels',
132
      children: [
133
        {
134
          label: 'Toggle Terminal',
135
          icon: 'i-lucide-square-terminal',
136
          kbds: ['⌃', '`'],
137
        },
138
        {
139
          label: 'Focus Problems',
140
          icon: 'i-lucide-triangle-alert',
141
          kbds: ['⇧', '⌘', 'M'],
142
        },
143
      ],
144
    },
145
  ])
146

147
  return (
148
    <div class="flex flex-col gap-3">
149
      <div class="flex flex-wrap gap-3 items-center">
150
        <DropdownMenu items={editorItems()}>
151
          <Button variant="outline">Editor menu</Button>
152
        </DropdownMenu>
153
      </div>
154
      <div class="text-sm text-muted-foreground flex flex-wrap gap-4">
155
        <span>
156
          Line numbers: <span class="font-medium">{String(showLineNumbers())}</span>
157
        </span>
158
        <span>
159
          Minimap: <span class="font-medium">{String(showMinimap())}</span>
160
        </span>
161
        <span>
162
          Preview tabs: <span class="font-medium">{String(previewTabs())}</span>
163
        </span>
164
        <span>
165
          Auto save: <span class="font-medium">{String(autoSave())}</span>
166
        </span>
167
        <span>
168
          Theme: <span class="font-medium uppercase">{theme()}</span>
169
        </span>
170
      </div>
171
    </div>
172
  )
173
}

Project / Release Actions#

A heavier project menu with move flows, release actions, mixed-content labels, and destructive project operations.

1
function ProjectReleaseActions() {
2
  const [lastAction, setLastAction] = createSignal('None')
3

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

7
  const projectItems: DropdownMenuT.Item[] = [
8
    {
9
      type: 'group',
10
      label: (
11
        <div class="flex gap-2 items-center">
12
          <span>Project: moraine</span>
13
          <span class={badgeClass}>main</span>
14
        </div>
15
      ),
16
      children: [
17
        {
18
          label: 'New File',
19
          icon: 'i-lucide-file-plus',
20
          kbds: ['⌘', 'N'],
21
          onSelect: () => setLastAction('New file'),
22
        },
23
        {
24
          label: 'New Folder',
25
          icon: 'i-lucide-folder-plus',
26
          kbds: ['⇧', '⌘', 'N'],
27
          onSelect: () => setLastAction('New folder'),
28
        },
29
        {
30
          label: 'Rename Project',
31
          icon: 'i-lucide-pencil',
32
          kbds: ['F2'],
33
          onSelect: () => setLastAction('Rename project'),
34
        },
35
        { type: 'separator' },
36
        {
37
          label: 'Move To…',
38
          icon: 'i-lucide-folder-input',
39
          children: [
40
            {
41
              type: 'group',
42
              label: 'Favorite Folders',
43
              children: [
44
                {
45
                  label: 'src/components',
46
                  icon: 'i-lucide-folder-open',
47
                  onSelect: () => setLastAction('Move to src/components'),
48
                },
49
                {
50
                  label: 'src/overlays',
51
                  icon: 'i-lucide-folder-open',
52
                  onSelect: () => setLastAction('Move to src/overlays'),
53
                },
54
                {
55
                  label: 'More Destinations',
56
                  icon: 'i-lucide-more-horizontal',
57
                  children: [
58
                    {
59
                      type: 'group',
60
                      children: [
61
                        {
62
                          label: 'docs/content',
63
                          icon: 'i-lucide-folder-open',
64
                          onSelect: () => setLastAction('Move to docs/content'),
65
                        },
66
                        {
67
                          label: 'archive/2025',
68
                          icon: 'i-lucide-folder-open',
69
                          onSelect: () => setLastAction('Move to archive/2025'),
70
                        },
71
                      ],
72
                    },
73
                  ],
74
                },
75
              ],
76
            },
77
          ],
78
        },
79
        {
80
          label: 'Copy Preview Link',
81
          icon: 'i-lucide-link',
82
          kbds: ['⌘', '⇧', 'C'],
83
          onSelect: () => setLastAction('Copy preview link'),
84
        },
85
      ],
86
    },
87
    {
88
      type: 'group',
89
      label: 'Release',
90
      children: [
91
        {
92
          label: 'Open Pull Request',
93
          icon: 'i-lucide-git-pull-request-arrow',
94
          onSelect: () => setLastAction('Open pull request'),
95
        },
96
        {
97
          label: 'Deploy Preview',
98
          description: 'Build preview for design review',
99
          icon: 'i-lucide-rocket',
100
          onSelect: () => setLastAction('Deploy preview'),
101
        },
102
        {
103
          label: (
104
            <div class="flex gap-2 items-center">
105
              <span>Ship to Production</span>
106
              <span class="text-[11px] text-amber-700 font-medium px-1.5 py-0.5 rounded-md bg-amber-100">
107
                Protected
108
              </span>
109
            </div>
110
          ),
111
          description: 'Requires review approval',
112
          icon: <span class="rounded-full bg-emerald-500 size-2 inline-block" />,
113
          onSelect: () => setLastAction('Ship to production'),
114
        },
115
      ],
116
    },
117
    {
118
      type: 'group',
119
      children: [
120
        {
121
          label: 'Archive Project',
122
          icon: 'i-lucide-archive',
123
          onSelect: () => setLastAction('Archive project'),
124
        },
125
        {
126
          label: 'Delete Project',
127
          icon: 'i-lucide-trash-2',
128
          color: 'destructive',
129
          onSelect: () => setLastAction('Delete Project'),
130
        },
131
      ],
132
    },
133
  ]
134

135
  return (
136
    <>
137
      <div class="flex flex-col gap-3 sm:flex-row sm:items-center sm:justify-between">
138
        <DropdownMenu items={projectItems}>
139
          <Button>Project actions</Button>
140
        </DropdownMenu>
141
        <p class="text-sm text-muted-foreground">
142
          Tip: use arrow keys to walk the nested “Move To…” and release sections.
143
        </p>
144
      </div>
145
      <div class="text-sm text-muted-foreground">
146
        Last action: <span class="font-medium">{lastAction()}</span>
147
      </div>
148
    </>
149
  )
150
}

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`	—	Trigger content used to open the dropdown menu.
class	`ClassValue`	—	Class applied to the component root or trigger element.
classes	`(OverlayMenuSharedClasses & DropdownMenuT.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: DropdownMenuT.ItemRenderProps) => ElementProps<HTMLDivElement> \| undefined) \| undefined`	—	Additional attributes for an interactive menu item.
itemRender	`ComponentOrElement<DropdownMenuT.ItemRenderProps> \| undefined`	—	Custom renderer for individual items.
items	`DropdownMenuT.Item[] \| undefined`	—	Items rendered in the menu body.
onClick	`JSX.EventHandlerUnion<HTMLSpanElement, MouseEvent> \| undefined`	—	Root trigger click handler.
onKeyDown	`JSX.EventHandlerUnion<HTMLSpanElement, KeyboardEvent> \| undefined`	—	Root trigger keyboard handler.
onOpenChange	`((open: boolean) => void) \| undefined`	—	Called whenever the menu requests an open state change.
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 & DropdownMenuT.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	`DropdownMenuT.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.