Skip to content

Search documentation

Search guides, examples, and component APIs.

Quick links
↑↓ NavigateEnter OpenEsc Close
Get started

Documentation navigation

Components / Overlays

DropdownMenu

A keyboard accessible list of actions.

Last changed in version 0.14.2: Improve keyboard navigation, action feedback, and selected colors across Vue components.

Interactive showcase

To try the safe triangle, hover More actions and move diagonally across Export toward Move workspace. Move straight down onto Export to switch submenus.

Install

Run in your project
bunx --bun @getweini/cli@latest add dropdown-menu

Start with this example

Import the files copied by the install command, then place the component in your Vue template. The text and values in the example belong to your app; change them to fit your task.

Vue
<script setup lang="ts">
import { ref } from 'vue'
import DropdownMenu from './components/ui/dropdown-menu/DropdownMenu.vue'
import DropdownMenuContent from './components/ui/dropdown-menu/DropdownMenuContent.vue'
import DropdownMenuItem from './components/ui/dropdown-menu/DropdownMenuItem.vue'
import DropdownMenuTrigger from './components/ui/dropdown-menu/DropdownMenuTrigger.vue'

const selected = ref('')
</script>

<template>
  <DropdownMenu @select="selected = $event.id">
    <DropdownMenuTrigger>Project actions</DropdownMenuTrigger>
    <DropdownMenuContent aria-label="Project actions">
      <DropdownMenuItem id="rename" label="Rename">Rename</DropdownMenuItem>
      <DropdownMenuItem id="archive" label="Archive" destructive>Archive</DropdownMenuItem>
    </DropdownMenuContent>
  </DropdownMenu>
  <p v-if="selected">Chosen action:{{ selected }}</p>
</template>

DropdownMenuContent points to its trigger with the shared floating surface and 12px gap. Items, checkbox/radio choices, groups, and nested submenus share roving focus, typeahead, RTL-aware arrows, and layer-local Escape handling.

When to use it

Row actions

Offer several commands without crowding each row.

Persistent choices

Use checkbox items for menu choices that stay selected after the menu closes.

More examples

Project actions

A selected item emits its ID to application code.

Project actions
<script setup lang="ts">
import DropdownMenu from './components/ui/dropdown-menu/DropdownMenu.vue'
import DropdownMenuContent from './components/ui/dropdown-menu/DropdownMenuContent.vue'
import DropdownMenuItem from './components/ui/dropdown-menu/DropdownMenuItem.vue'
import DropdownMenuSeparator from './components/ui/dropdown-menu/DropdownMenuSeparator.vue'
import DropdownMenuTrigger from './components/ui/dropdown-menu/DropdownMenuTrigger.vue'
</script>
<template>
  <DropdownMenu @select="$emit('action', $event.id)">
    <DropdownMenuTrigger>Project actions</DropdownMenuTrigger>
    <DropdownMenuContent aria-label="Project actions">
      <DropdownMenuItem id="rename" label="Rename">Rename</DropdownMenuItem>
      <DropdownMenuSeparator />
      <DropdownMenuItem id="archive" label="Archive" destructive>Archive</DropdownMenuItem>
    </DropdownMenuContent>
  </DropdownMenu>
</template>

Checkbox option

The checked model remains in application state.

Checkbox option
<script setup lang="ts">
import { ref } from 'vue'
import DropdownMenu from './components/ui/dropdown-menu/DropdownMenu.vue'
import DropdownMenuCheckboxItem from './components/ui/dropdown-menu/DropdownMenuCheckboxItem.vue'
import DropdownMenuContent from './components/ui/dropdown-menu/DropdownMenuContent.vue'
import DropdownMenuTrigger from './components/ui/dropdown-menu/DropdownMenuTrigger.vue'

const showArchived = ref(false)
</script>
<template>
  <DropdownMenu>
    <DropdownMenuTrigger>Display options</DropdownMenuTrigger>
    <DropdownMenuContent aria-label="Display options">
      <DropdownMenuCheckboxItem id="archived" label="Show archived" v-model:checked="showArchived">
        Show archived
      </DropdownMenuCheckboxItem>
    </DropdownMenuContent>
  </DropdownMenu>
</template>

Complete API

Every public prop, model, event, slot, and exposed member of the installed Vue parts is listed below. “Not set” means you can leave that value out; “Required” means you must provide it. Native HTML attributes also work where the component uses a native element.

DropdownMenu

Complete API for DropdownMenu
NameType or signatureDefaultWhat it does
itemspropreadonly DropdownMenuItem[] | undefinedNot setData items displayed by this component.
labelpropstring | undefinedNot setVisible or accessible name for this item.
openmodelboolean | undefinedNot setCurrent open state. Use v-model:open to keep it in sync with your page.
defaultOpenpropboolean | undefinedNot setStarting open state when the parent does not control open.
disabledpropboolean | undefinedNot setPrevent interaction and show the disabled state.
widthpropnumber | undefined224Choose the width of this content.
gappropnumber | undefined12Space in pixels between the trigger and floating content.
alignprop"start" | "end" | "center" | undefined"start"Choose how content aligns within its container.
sideprop"top" | "bottom" | undefined"bottom"Choose the side on which this content appears.
dirprop"ltr" | "rtl" | undefinedNot setSet the text direction used for keyboard and layout behavior.
selectevent[item: DropdownMenuAction]—Emitted when the user selects an item.
update:openevent[value: boolean | undefined]—Requests a new open value from the parent.
openChangeevent[open: boolean]—Emitted after this value or state changes.
triggerslot{ props: OverlayTriggerProps; open: boolean; }OptionalContent for the trigger area of DropdownMenu.
defaultslot{}OptionalContent shown inside DropdownMenu.
itemslot{ item: DropdownMenuDataItem; }OptionalContent for the item area of DropdownMenu.
openexposed(fromLast?: boolean) => void—Open this component from application code.
closeexposed(restoreFocus?: boolean) => void—Close this component from application code.

DropdownMenuCheckboxItem

Complete API for DropdownMenuCheckboxItem
NameType or signatureDefaultWhat it does
idpropstringRequiredGive the control an ID so a label or description can refer to it.
labelpropstringRequiredVisible or accessible name for this item.
checkedmodelboolean | undefinedfalseCurrent checked state of this choice.
disabledpropboolean | undefinedNot setPrevent interaction and show the disabled state.
destructivepropboolean | undefinedNot setShow that an action has a potentially destructive result.
shortcutpropstring | undefinedNot setKeyboard shortcut displayed beside this action.
selectevent[action: DropdownMenuAction]—Emitted when the user selects an item.
update:checkedevent[value: boolean]—Requests a new checked value from the parent.
checkedChangeevent[checked: boolean]—Emitted after this value or state changes.
defaultslot(() => unknown) | undefinedOptionalContent shown inside DropdownMenuCheckboxItem.
prefixslot(() => unknown) | undefinedOptionalContent shown before the main label or value.
suffixslot(() => unknown) | undefinedOptionalContent shown after the main label or value.

DropdownMenuContent

Complete API for DropdownMenuContent
NameType or signatureDefaultWhat it does
arrowpropboolean | undefinedtrueControls the arrow behavior of DropdownMenuContent.
defaultslot{}OptionalContent shown inside DropdownMenuContent.

DropdownMenuGroup

Complete API for DropdownMenuGroup
NameType or signatureDefaultWhat it does
labelpropstring | undefinedNot setVisible or accessible name for this item.
defaultslot{}OptionalContent shown inside DropdownMenuGroup.

DropdownMenuItem

Complete API for DropdownMenuItem
NameType or signatureDefaultWhat it does
itempropDropdownMenuAction | undefinedNot setControls the item behavior of DropdownMenuItem.
idpropstring | undefinedNot setGive the control an ID so a label or description can refer to it.
labelpropstring | undefinedNot setVisible or accessible name for this item.
disabledpropboolean | undefinedNot setPrevent interaction and show the disabled state.
destructivepropboolean | undefinedNot setShow that an action has a potentially destructive result.
shortcutpropstring | undefinedNot setKeyboard shortcut displayed beside this action.
selectevent[action: DropdownMenuAction]—Emitted when the user selects an item.
defaultslot(() => unknown) | undefinedOptionalContent shown inside DropdownMenuItem.
prefixslot(() => unknown) | undefinedOptionalContent shown before the main label or value.
suffixslot(() => unknown) | undefinedOptionalContent shown after the main label or value.

DropdownMenuLabel

Complete API for DropdownMenuLabel
NameType or signatureDefaultWhat it does
defaultslot{}OptionalContent shown inside DropdownMenuLabel.

DropdownMenuRadioGroup

Complete API for DropdownMenuRadioGroup
NameType or signatureDefaultWhat it does
modelValuemodelstring | undefinedNot setCurrent value. Use v-model to keep it in sync with your page.
defaultValuepropstring | undefinedNot setStarting value when the parent does not control the value.
update:modelValueevent[value: string | undefined]—Requests a new model value from the parent.
valueChangeevent[value: string]—Emitted after this value or state changes.
defaultslot{}OptionalContent shown inside DropdownMenuRadioGroup.

DropdownMenuRadioItem

Complete API for DropdownMenuRadioItem
NameType or signatureDefaultWhat it does
idpropstringRequiredGive the control an ID so a label or description can refer to it.
valuepropstringRequiredValue represented by this control or option.
labelpropstringRequiredVisible or accessible name for this item.
disabledpropboolean | undefinedNot setPrevent interaction and show the disabled state.
shortcutpropstring | undefinedNot setKeyboard shortcut displayed beside this action.
selectevent[action: DropdownMenuAction]—Emitted when the user selects an item.
defaultslot(() => unknown) | undefinedOptionalContent shown inside DropdownMenuRadioItem.
prefixslot(() => unknown) | undefinedOptionalContent shown before the main label or value.
suffixslot(() => unknown) | undefinedOptionalContent shown after the main label or value.

DropdownMenuSeparator

Complete API for DropdownMenuSeparator
NameType or signatureDefaultWhat it does

DropdownMenuSub

Complete API for DropdownMenuSub
NameType or signatureDefaultWhat it does
openmodelboolean | undefinedNot setCurrent open state. Use v-model:open to keep it in sync with your page.
defaultOpenpropboolean | undefinedNot setStarting open state when the parent does not control open.
disabledpropboolean | undefinedNot setPrevent interaction and show the disabled state.
update:openevent[value: boolean | undefined]—Requests a new open value from the parent.
openChangeevent[open: boolean]—Emitted after this value or state changes.
defaultslot{}OptionalContent shown inside DropdownMenuSub.

DropdownMenuSubContent

Complete API for DropdownMenuSubContent
NameType or signatureDefaultWhat it does
defaultslot{}OptionalContent shown inside DropdownMenuSubContent.

DropdownMenuSubTrigger

Complete API for DropdownMenuSubTrigger
NameType or signatureDefaultWhat it does
defaultslot() => unknownRequiredContent shown inside DropdownMenuSubTrigger.
prefixslot(() => unknown) | undefinedOptionalContent shown before the main label or value.
suffixslot(() => unknown) | undefinedOptionalContent shown after the main label or value.

DropdownMenuTrigger

Complete API for DropdownMenuTrigger
NameType or signatureDefaultWhat it does
asChildpropboolean | undefinedNot setUse one child element as the control instead of adding another wrapper.
defaultslot{}OptionalContent shown inside DropdownMenuTrigger.
Public type definitions
Public types
// packages/frameworks/vue/components/dropdown-menu/types.ts
// ------- TYPES -------

export interface DropdownMenuAction {
  id: string
  label: string
  disabled?: boolean
  destructive?: boolean
  shortcut?: string
  kind?: 'item' | 'checkbox' | 'radio'
  checked?: boolean
  value?: string
}

export type DropdownMenuDataItem = Omit<DropdownMenuAction, 'kind' | 'checked' | 'value'> & {
  kind?: 'item'
}

export type DropdownMenuItem = DropdownMenuDataItem | { id: string; kind: 'separator' }

export interface DropdownMenuProps {
  items?: readonly DropdownMenuItem[]
  label?: string
  open?: boolean
  defaultOpen?: boolean
  disabled?: boolean
  width?: number
  gap?: number
  align?: 'start' | 'center' | 'end'
  side?: 'top' | 'bottom'
  dir?: 'ltr' | 'rtl'
}

export interface DropdownMenuTriggerProps {
  asChild?: boolean
}

export interface DropdownMenuContentProps {
  arrow?: boolean
}

export interface DropdownMenuCheckboxItemProps {
  id: string
  label: string
  checked?: boolean
  disabled?: boolean
  destructive?: boolean
  shortcut?: string
}

export interface DropdownMenuRadioGroupProps {
  modelValue?: string
  defaultValue?: string
}

export interface DropdownMenuRadioItemProps {
  id: string
  value: string
  label: string
  disabled?: boolean
  shortcut?: string
}

export interface DropdownMenuSubProps {
  open?: boolean
  defaultOpen?: boolean
  disabled?: boolean
}

Implementation notes

  • Selection emits an action; application code owns the side effect.
  • The shortcut prop displays a hint and does not register a global keyboard shortcut.

Accessibility and localization

  • Name the content menu and give each item a stable ID and readable label.
  • Arrow keys and typeahead skip disabled items; Escape restores trigger focus.

Source contract and editing guidance