Skip to main content

DropdownMenu

Open a compact action menu from a visible trigger.

Props
Slots

Anatomy#

DropdownMenu [component; no DOM]
├── DropdownMenu.Trigger [part; slot=trigger]
├── overlay [slot]
└── positioner [internal]
    └── DropdownMenu.Content [part; slot=content]
        ├── group [slot]
        │   ├── groupLabel [slot]
        │   └── item [slot]
        ├── item [slot]
        │   ├── itemLeading [slot]
        │   ├── itemWrapper [slot]
        │   │   ├── itemLabel [slot]
        │   │   └── itemDescription [slot]
        │   └── itemTrailing [slot]
        │       ├── itemKbds [slot]
        │       ├── itemIndicator [slot]
        │       └── itemSubIndicator [slot]
        └── separator [slot]

Content is portaled; grouped items use the same item subtree as ungrouped items.

Usage#

Use DropdownMenu for a compact set of actions from a visible trigger. Use Select for choosing a form value. Use ContextMenu for actions at a pointer location. Use Popover when the content is not a list of commands. Use Dialog when the user must complete a modal task.

import { Button, DropdownMenu } from 'moraine'

export function Example() {
  return (
    <DropdownMenu>
      <DropdownMenu.Trigger as={Button}>Actions</DropdownMenu.Trigger>
      <DropdownMenu.Content items={[{ label: 'Copy' }]} />
    </DropdownMenu>
  )
}

Trigger and items#

DropdownMenu.Trigger adds click, keyboard, and ARIA behavior to the element it renders. It renders a button; pass as to render another component such as Button, and disabled to prevent opening. Describe each action in items. An entry that is an array of items forms its own group, and the menu draws a separator between groups. An item accepts icon, description, kbds, disabled, and variant: 'danger', and runs onSelect before the menu closes.

<DropdownMenu>
  <DropdownMenu.Trigger as={Button} trailing="i-lucide:chevron-down">
    Account options
  </DropdownMenu.Trigger>
  <DropdownMenu.Content
    items={[
      { label: 'Edit profile', icon: 'i-lucide:user' },
      { label: 'Billing details', icon: 'i-lucide:credit-card' },
    ]}
  />
</DropdownMenu>

Stateful and nested items#

Control a checkbox item with checked and onCheckedChange, or omit checked and set defaultChecked for uncontrolled state. A radio-group item owns the selected value for its radio items: pass value and onValueChange (or defaultValue for uncontrolled state) once on the group, and give each radio item only its value. Selecting a checkbox or radio item keeps the menu open. Nested children create submenus. Disabled items stay visible but cannot be activated.

A parent item with children can take open and onOpenChange to control its submenu. onOpenChange reports every open or close request from pointer, keyboard, or click interaction. With a controlled open, the submenu stays at the prop value until you update it.

<DropdownMenu.Content
  items={[
    {
      type: 'checkbox',
      label: 'Show bookmarks bar',
      checked: showBookmarks(),
      onCheckedChange: setShowBookmarks,
    },
    {
      label: 'Theme',
      children: [
        {
          type: 'radio-group',
          value: theme(),
          onValueChange: setTheme,
          items: [{ type: 'radio', label: 'System', value: 'system' }],
        },
      ],
    },
  ]}
/>

Dismissal and positioning#

Escape and outside interaction close the menu by default. Set closeOnEscape={false} or closeOnOutsideClick={false} to keep it open and receive onClosePrevented for each blocked attempt. modal hides the rest of the page from assistive technology and prevents the native action of outside pointer presses while the menu is open. By default the menu also locks body scroll and renders an overlay behind the content; set preventScroll={false} to keep the page scrollable. placement (default 'bottom'), align, gutter, shift, flip, and slide tune where the content opens.

<DropdownMenu closeOnOutsideClick={false} onClosePrevented={() => setHint(true)} flip={false}>
  {/* Trigger and Content */}
</DropdownMenu>

Keyboard interaction#

Key Description
↵ / Space / ↓ Opens the menu from the trigger and focuses the first item.
↑ Opens the menu from the trigger and focuses the last item.
↓ / ↑ Moves focus to the next or previous item.
↖ / ↘ Moves focus to the first or last item.
Printable characters Moves focus to the next item whose text starts with the typed characters.
→ Opens the submenu of the focused item.
← Closes the current submenu and returns to its parent item.
↵ / Space Activates the focused item, or opens its submenu.
Esc Closes the current menu layer and restores focus.
⇥ Closes the menu.

Examples#

Open account actions#

Compose a visible trigger with profile, billing, and shortcut items.

import { Button, DropdownMenu } from 'moraine'
import type { DropdownMenuT } from 'moraine'

const ACTIONS = [
  { label: 'Edit profile', icon: 'i-lucide:user' },
  { label: 'Billing details', icon: 'i-lucide:credit-card' },
  { label: 'Keyboard shortcuts', icon: 'i-lucide:keyboard' },
] satisfies DropdownMenuT.Item[]

export function TriggerItems() {
  return (
    <DropdownMenu>
      <DropdownMenu.Trigger as={Button} variant="outline" trailing="i-lucide:chevron-down">
        Account options
      </DropdownMenu.Trigger>
      <DropdownMenu.Content items={ACTIONS} />
    </DropdownMenu>
  )
}

Toggle bookmarks and choose a theme#

Keep checkbox and radio values in application state. Nested children open a theme submenu.

import { Button, DropdownMenu } from 'moraine'
import type { DropdownMenuT } from 'moraine'
import { createMemo, createSignal } from 'solid-js'

export function StatefulItems() {
  const [showBookmarks, setShowBookmarks] = createSignal(true)
  const [theme, setTheme] = createSignal('system')

  const items = createMemo<DropdownMenuT.Item[]>(() => [
    {
      type: 'checkbox',
      label: 'Show bookmarks bar',
      checked: showBookmarks(),
      onCheckedChange: setShowBookmarks,
    },
    { type: 'separator' },
    {
      label: 'Theme',
      children: [
        {
          type: 'radio-group',
          value: theme(),
          onValueChange: setTheme,
          items: [
            { type: 'radio', label: 'Light', value: 'light' },
            { type: 'radio', label: 'Dark', value: 'dark' },
            { type: 'radio', label: 'System', value: 'system' },
          ],
        },
      ],
    },
  ])

  return (
    <DropdownMenu>
      <DropdownMenu.Trigger as={Button} variant="outline">
        View preferences
      </DropdownMenu.Trigger>
      <DropdownMenu.Content items={items()} />
    </DropdownMenu>
  )
}

Customize a workspace project view#

Toggle visible fields, include archived projects, and choose a sort order. The list updates from application-owned state; saving a shared view stays disabled for viewers.

import { Button, DropdownMenu } from 'moraine'
import type { DropdownMenuT } from 'moraine'
import { createMemo, createSignal, For, Show } from 'solid-js'

const PROJECTS = [
  { name: 'Design system', owner: 'Alex', updated: 3, archived: false },
  { name: 'Customer portal', owner: 'Sam', updated: 2, archived: false },
  { name: 'Website v1', owner: 'Jordan', updated: 1, archived: true },
]

export function WorkspaceView() {
  const [showArchived, setShowArchived] = createSignal(false)
  const [showOwner, setShowOwner] = createSignal(true)
  const [sort, setSort] = createSignal('updated')
  const projects = createMemo(() => {
    const includeArchived = showArchived()
    const byName = sort() === 'name'
    return PROJECTS.filter((project) => includeArchived || !project.archived).sort((a, b) =>
      byName ? a.name.localeCompare(b.name) : b.updated - a.updated,
    )
  })
  const items = createMemo<DropdownMenuT.Item[]>(() => [
    {
      type: 'group',
      label: 'Visible fields',
      items: [
        {
          type: 'checkbox',
          label: 'Project owner',
          checked: showOwner(),
          onCheckedChange: setShowOwner,
        },
        {
          type: 'checkbox',
          label: 'Archived projects',
          checked: showArchived(),
          onCheckedChange: setShowArchived,
        },
      ],
    },
    { type: 'separator' },
    {
      label: 'Sort projects',
      icon: 'i-lucide:arrow-down-wide-narrow',
      children: [
        {
          type: 'radio-group',
          value: sort(),
          onValueChange: setSort,
          items: [
            { type: 'radio', label: 'Recently updated', value: 'updated' },
            { type: 'radio', label: 'Name', value: 'name' },
          ],
        },
      ],
    },
    { type: 'separator' },
    {
      label: 'Reset view',
      icon: 'i-lucide:rotate-ccw',
      onSelect: () => {
        setShowArchived(false)
        setShowOwner(true)
        setSort('updated')
      },
    },
    {
      label: 'Save for everyone',
      description: 'Workspace administrator permission required',
      disabled: true,
      icon: 'i-lucide:lock',
    },
  ])

  return (
    <section
      class="p-4 border border-border rounded-lg bg-card max-w-lg w-full space-y-4"
      aria-label="Workspace projects"
    >
      <div class="flex flex-wrap gap-3 items-center justify-between">
        <div>
          <h4 class="text-sm font-semibold">Workspace projects</h4>
          <p class="text-xs text-muted-foreground">
            Customize this view without changing project data.
          </p>
        </div>
        <DropdownMenu>
          <DropdownMenu.Trigger as={Button} variant="outline" leading="i-lucide:sliders-horizontal">
            View
          </DropdownMenu.Trigger>
          <DropdownMenu.Content items={items()} />
        </DropdownMenu>
      </div>
      <ul class="divide-border divide-y">
        <For each={projects()}>
          {(project) => (
            <li class="text-sm py-3 flex gap-3 items-center justify-between">
              <span>
                {project.name}
                <Show when={project.archived}>
                  <span class="text-xs text-muted-foreground ms-2">Archived</span>
                </Show>
              </span>
              <Show when={showOwner()}>
                <span class="text-xs text-muted-foreground">{project.owner}</span>
              </Show>
            </li>
          )}
        </For>
      </ul>
      <p role="status" class="text-xs text-muted-foreground">
        {projects().length} projects · Sorted by {sort() === 'name' ? 'name' : 'recently updated'}
      </p>
    </section>
  )
}

Switch layout and show archived#

Checkbox and radio items update a live status line next to the trigger.

import { Button, DropdownMenu } from 'moraine'
import type { DropdownMenuT } from 'moraine'
import { createMemo, createSignal } from 'solid-js'

export function CheckboxRadio() {
  const [showArchived, setShowArchived] = createSignal(false)
  const [layout, setLayout] = createSignal('grid')
  const items = createMemo<DropdownMenuT.Item[]>(() => [
    {
      type: 'checkbox',
      label: 'Show archived',
      checked: showArchived(),
      onCheckedChange: setShowArchived,
    },
    { type: 'separator' },
    {
      type: 'radio-group',
      value: layout(),
      onValueChange: setLayout,
      items: [
        { type: 'radio', label: 'Grid', value: 'grid' },
        { type: 'radio', label: 'List', value: 'list' },
      ],
    },
  ])

  return (
    <div class="flex gap-3 items-center">
      <DropdownMenu>
        <DropdownMenu.Trigger as={Button} variant="outline">
          View options
        </DropdownMenu.Trigger>
        <DropdownMenu.Content items={items()} />
      </DropdownMenu>
      <p class="text-sm text-muted-foreground">
        {layout()} layout, archived: {String(showArchived())}
      </p>
    </div>
  )
}

Move a file into a folder#

Nested children open a folder submenu. Download stays on the root menu.

import { Button, DropdownMenu } from 'moraine'

export function Submenus() {
  return (
    <DropdownMenu>
      <DropdownMenu.Trigger as={Button} variant="outline">
        File
      </DropdownMenu.Trigger>
      <DropdownMenu.Content
        items={[
          {
            label: 'Move to…',
            icon: 'i-lucide:folder-input',
            children: [
              {
                type: 'group',
                label: 'Folders',
                items: [
                  { label: 'Inbox', icon: 'i-lucide:inbox' },
                  { label: 'Archive', icon: 'i-lucide:archive' },
                ],
              },
            ],
          },
          { label: 'Download', icon: 'i-lucide:download' },
        ]}
      />
    </DropdownMenu>
  )
}

Share with a disabled export#

kbds displays shortcut notation. A disabled Export item stays visible but cannot be activated.

import { Button, DropdownMenu } from 'moraine'

export function ShortcutsDisabled() {
  return (
    <DropdownMenu>
      <DropdownMenu.Trigger as={Button} variant="outline">
        Share
      </DropdownMenu.Trigger>
      <DropdownMenu.Content
        items={[
          { label: 'Copy link', icon: 'i-lucide:link', kbds: ['⌘', 'C'] },
          { label: 'Export', icon: 'i-lucide:download', kbds: ['⌘', 'E'], disabled: true },
        ]}
      />
    </DropdownMenu>
  )
}

Use headerRender and footerRender on DropdownMenu.Content to pin a user identity banner, search input, or status bar above and below the scrollable menu items.

import { Button, DropdownMenu } from 'moraine'

export function ContentHeaderFooter() {
  return (
    <DropdownMenu>
      <DropdownMenu.Trigger as={Button} variant="outline">
        Workspace
      </DropdownMenu.Trigger>
      <DropdownMenu.Content
        headerRender={
          <div class="text-xs px-2 py-1.5 border-b border-border">
            <p class="font-medium">Acme Corp</p>
            <p class="text-muted-foreground">[email protected]</p>
          </div>
        }
        footerRender={
          <div class="text-[11px] text-muted-foreground px-2 py-1 border-t border-border flex justify-between">
            <span>Moraine UI</span>
            <span>Free Plan</span>
          </div>
        }
        items={[
          { label: 'Settings', icon: 'i-lucide:settings' },
          { label: 'Team members', icon: 'i-lucide:users' },
          { type: 'separator' },
          { label: 'Log out', icon: 'i-lucide:log-out' },
        ]}
      />
    </DropdownMenu>
  )
}

API Reference#

Attributes#

Attributes
data-closed
Slot: dropdown-menu-triggerdropdown-menu-content
Description: Present when disclosure or transition content is closed.
data-disabled
Slot: dropdown-menu-triggerdropdown-menu-item
Description: Present when the component, slot, or item is disabled.
data-expanded
Slot: dropdown-menu-triggerdropdown-menu-contentdropdown-menu-item
Description: Present when the panel, accordion, or menu is expanded.
data-align
Slot: dropdown-menu-content
Description: Stores the resolved alignment of positioned content.
data-side
Slot: dropdown-menu-content
Description: Stores the resolved floating or drawer content side.
data-danger
Slot: dropdown-menu-item
Description: Present when the action has danger semantics.
data-highlighted
Slot: dropdown-menu-item
Description: Present when the item is highlighted by pointer or keyboard navigation.
data-selected
Slot: dropdown-menu-item
Description: Present when the item or tab is selected.

Props#

DropdownMenu#

Prop

Trigger#

Renders a <button> element by default.

Prop

Content#

Props for the DropdownMenu content component. Renders a <div> element by default.

Prop