Menu
updatedOne menu to rule them all. A dropdown and a context menu in one component that attaches to whatever it sits in.
Open Props in the corner of the example to try size. It goes from xs to xl, and items match the height of an Input of the same size. A submenu takes its parent's size unless you give it its own.
Installation
Usage
<script setup lang="ts">
import { Button } from '@/components/ui/button'
import { Menu, MenuItem } from '@/components/ui/menu'
</script>
<template>
<Button>
Edit
<Menu>
<MenuItem @select="copy">Copy</MenuItem>
<MenuItem @select="paste">Paste</MenuItem>
</Menu>
</Button>
</template>
Put Menu inside the element that opens it, and it attaches there. No trigger needed. It opens on click, or, with context-menu, on right-click and long press. One component, both menus.
v-model holds the open state, and show(), hide() and toggle() work from code. By default, a click outside only closes the menu. More on overlays.
MenuItem: an action; firesselectand closes the menuMenuCheckboxItem,MenuRadioGroup+MenuRadioItem: settingsMenuSub,MenuSubTrigger,MenuSubContent: submenusMenuLabel,MenuGroup,MenuSeparator: structureMenuShortcut: a key hint at the end, display only
Items look like Select's.
Examples
With a trigger
Prefer the classic shape? Put a MenuTrigger next to the Menu, and the menu attaches to the trigger instead of the parent. It renders a button, or your own element with as-child. Handy for a table row's actions.
Touch position
With touch-position, the menu opens where you clicked, not at the target's edge.
Open state
While the menu is open, its target gets data-state="open", so you can style it with data-[state=open]:. Works for click and context menus alike.
- Ada LovelaceNotes on the engine
- Alan TuringA question about machines
- Grace HopperFound a bug
Sizing
fit: at least as wide as the targetmax-height,max-width: any CSS length; the menu scrolls past itcover: sits on top of the target, at least its size
Checkbox items
MenuCheckboxItem toggles a setting. Bind it with v-model.
Radio group
MenuRadioItems inside a MenuRadioGroup pick one option. Bind the group with v-model.
Mixing plain items with checkbox or radio items? Give the plain ones inset to line up the text.
Context menu
With context-menu, the menu opens at the pointer on right-click, or after a long press on touch screens. A right-click elsewhere closes it. With :modal="false", a right-click elsewhere in the target moves the menu there instead.
Click and right-click on one element
One element, two menus: one on click, one on right-click with context-menu. Render both from one v-for, and you write the items once.
Last action: nothing yet
One menu for many targets
A menu doesn't have to live in every row. In the demo, 10,000 rows of a virtualized ScrollArea share one context menu on their container, and a contextmenu listener remembers which row was pressed.
target attaches the menu somewhere else: pass a CSS selector or an element. false attaches it to nothing, for a menu opened only from code: it opens in the middle of the viewport, or at the event's position when show(event) gets one with context-menu or touch-position.
Last action: nothing yet
Virtualized items
The menu can hold a virtualized ScrollArea. Arrow keys move through the items, and more render as you reach the edge.
Positioning
anchor picks a point on the target, self a point on the menu, and the menu moves so they meet. Each is a vertical part (top, center, bottom) plus a horizontal one (left, middle, right, or start and end, which follow the reading direction). The default, anchor="bottom start" with self="top start", opens below the target, aligned to its start.
offset pushes the menu away by [x, y] pixels. There's a 4px gap by default; :offset="[0, 0]" removes it.
Doesn't fit? It flips to the side with more room, shrinks and scrolls.
Non-modal
With :modal="false", the page keeps scrolling while the menu is open, and another row's menu opens in one click instead of two.
API Reference
Every part takes a class that merges with its own. On Menu, it styles the panel.
Menu
| Prop | Default | Type and description |
|---|---|---|
| contextMenu | — | booleanOpens the menu at the pointer on right-click, and on touch screens after a long press, instead of on click. |
| target | true | string | boolean | ElementThe element the menu attaches to: |
| noParentEvent | — | booleanLeaves the target without listeners, so only |
| anchor | — | "top left" | "top middle" | "top right" | "top start" | "top end" | "center left" | "center middle" | "center right" | "center start" | "center end" | "bottom left" | "bottom middle" | "bottom right" | "bottom start" | "bottom end"The point on the target the menu is placed against, as a vertical part ( |
| self | — | "top left" | "top middle" | "top right" | "top start" | "top end" | "center left" | "center middle" | "center right" | "center start" | "center end" | "bottom left" | "bottom middle" | "bottom right" | "bottom start" | "bottom end"The point on the menu that meets the anchor, in the same form as |
| offset | — | [number, number]Pixels |
| cover | — | booleanPlaces the menu over its target and makes it at least the target's size. |
| fit | — | booleanMakes the menu at least as wide as its target. |
| touchPosition | — | booleanOpens the menu where the target was clicked instead of at its edge. |
| autoClose | — | booleanCloses the menu on any click inside it, not only on an item. For menus with buttons or other content that is not an item. |
| persistent | — | booleanKeeps the menu open on Escape and on outside clicks. Only an item, |
| modal | true | booleanShuts the page while the menu is open: an outside click only closes it, and the page does not scroll. A scrim takes the first outside click so nothing under it is activated. |
| maxHeight | — | stringThe menu's maximum height as a CSS length. Past it the menu scrolls. |
| maxWidth | — | stringThe menu's maximum width as a CSS length. |
| size | — | MenuSizeItem size, from 28px for |
| modelValue | false | booleanWhether the menu is open, bound with |
| Event | Payload and description |
|---|---|
| update:modelValue | [value: boolean]Fires when the menu opens or closes. |
| Slot | Scope and description |
|---|---|
| default | {}The items, labels, separators and submenus, or any other content. |
| Member | Type and description |
|---|---|
| show | (event?: Event | undefined) => voidOpens the menu. Given a mouse event and |
| hide | () => voidCloses the menu. |
| toggle | (event?: Event | undefined) => voidOpens the menu if it is closed, closes it otherwise. |
MenuTrigger
| Prop | Default | Type and description |
|---|---|---|
| asChild | — | booleanRender the single child instead of a wrapper, merging this part's attributes and classes onto it. |
| as | "button" | AsTag | ComponentThe element or component to render; a |
| Slot | Scope and description |
|---|---|
| default | {}The button that opens the |
MenuItem
| Prop | Default | Type and description |
|---|---|---|
| disabled | — | booleanDisables the item: it is skipped by the keyboard and cannot be chosen. |
| textValue | — | stringText used for typeahead instead of the item's text content. |
| asChild | — | booleanRender the single child instead of a wrapper, merging this part's attributes and classes onto it. |
| as | — | AsTag | ComponentThe element or component to render. |
| inset | — | booleanIndents the text to line up with items that have an indicator. |
| color | — | MenuItemColor | (string & {})Colour role the item, its icon and its hover layer are drawn in, such as |
| Event | Payload and description |
|---|---|
| select | [event: Event]Fires when the item is chosen by click or keyboard. Call |
| Slot | Scope and description |
|---|---|
| default | {}The label, with an optional leading icon and a |
MenuCheckboxItem
| Prop | Default | Type and description |
|---|---|---|
| modelValue | — | CheckedStateWhether it is checked, bound with |
| disabled | — | booleanDisables the item: it is skipped by the keyboard and cannot be chosen. |
| textValue | — | stringText used for typeahead instead of the item's text content. |
| asChild | — | booleanRender the single child instead of a wrapper, merging this part's attributes and classes onto it. |
| as | — | AsTag | ComponentThe element or component to render. |
| Event | Payload and description |
|---|---|
| select | [event: Event]Fires when the item is chosen by click or keyboard. Call |
| update:modelValue | [payload: boolean]Fires when the item is toggled. |
| Slot | Scope and description |
|---|---|
| indicator-icon | {}The icon shown while checked, a check by default. |
| default | {}The label. |
MenuRadioItem
| Prop | Default | Type and description |
|---|---|---|
| value* | — | AcceptableValueThe value this item puts in the group's |
| disabled | — | booleanDisables the item: it is skipped by the keyboard and cannot be chosen. |
| textValue | — | stringText used for typeahead instead of the item's text content. |
| asChild | — | booleanRender the single child instead of a wrapper, merging this part's attributes and classes onto it. |
| as | — | AsTag | ComponentThe element or component to render. |
| Event | Payload and description |
|---|---|
| select | [event: Event]Fires when the item is chosen by click or keyboard. Call |
| Slot | Scope and description |
|---|---|
| indicator-icon | {}The icon shown while checked, a dot by default. |
| default | {}The label. |
MenuSub
| Prop | Default | Type and description |
|---|---|---|
| open | — | booleanWhether it is open, bound with |
| Event | Payload and description |
|---|---|
| update:open | [payload: boolean]Fires when it opens or closes. |
| Slot | Scope and description |
|---|---|
| default | {}A |
MenuGroup
| Prop | Default | Type and description |
|---|---|---|
| asChild | — | booleanRender the single child instead of a wrapper, merging this part's attributes and classes onto it. |
| as | — | AsTag | ComponentThe element or component to render. |
| Slot | Scope and description |
|---|---|
| default | {}Related items. |
MenuLabel
| Prop | Default | Type and description |
|---|---|---|
| asChild | — | booleanRender the single child instead of a wrapper, merging this part's attributes and classes onto it. |
| as | — | AsTag | ComponentThe element or component to render. |
| inset | — | booleanIndents the text to line up with items that have an indicator. |
| Slot | Scope and description |
|---|---|
| default | {}The label text. |
MenuRadioGroup
| Prop | Default | Type and description |
|---|---|---|
| modelValue | — | AcceptableValueThe value of the checked item, bound with |
| asChild | — | booleanRender the single child instead of a wrapper, merging this part's attributes and classes onto it. |
| as | — | AsTag | ComponentThe element or component to render. |
| Event | Payload and description |
|---|---|
| update:modelValue | [payload: AcceptableValue]Fires when another item is checked. |
| Slot | Scope and description |
|---|---|
| default | {}The radio items. |
MenuSeparator
| Prop | Default | Type and description |
|---|---|---|
| asChild | — | booleanRender the single child instead of a wrapper, merging this part's attributes and classes onto it. |
| as | — | AsTag | ComponentThe element or component to render. |
MenuShortcut
| Slot | Scope and description |
|---|---|
| default | {}The key combination, for display only. It does not register the shortcut. |
MenuSubContent
| Prop | Default | Type and description |
|---|---|---|
| forceMount | — | booleanKeeps the panel mounted while closed, for animating it with a JavaScript library. |
| memoDependencies | — | unknown[]Values that should re-run the position update when they change. |
| sideOffset | — | numberDistance in pixels from the trigger. |
| sideFlip | — | booleanFlips to the opposite side when the preferred one would overflow. |
| alignOffset | — | numberOffset in pixels from the |
| alignFlip | — | booleanFlips the alignment when it would overflow. |
| avoidCollisions | — | booleanKeeps the panel inside the collision boundary by flipping and shifting it. |
| collisionBoundary | — | Element | (Element | null)[] | nullThe element or elements used as the collision boundary. The viewport by default. |
| collisionPadding | — | number | Partial<Record<"top" | "right" | "bottom" | "left", number>>Distance in pixels from the boundary edges where collisions start. |
| arrowPadding | — | numberPadding between an arrow and the panel's corners. |
| hideShiftedArrow | — | booleanHides an arrow when the panel is shifted so far that the arrow would not point at the trigger. |
| sticky | — | "partial" | "always"
|
| hideWhenDetached | — | booleanHides the panel when the trigger is scrolled out of view. |
| positionStrategy | — | "absolute" | "fixed"The CSS position used to place the panel. |
| updatePositionStrategy | — | "always" | "optimized"
|
| disableUpdateOnLayoutShift | — | booleanStops recomputing the position when the layout shifts. |
| prioritizePosition | — | booleanKeeps the preferred side and alignment and lets the panel overflow instead of flipping. |
| reference | — | ReferenceElementA virtual element to position against instead of the trigger. |
| asChild | — | booleanRender the single child instead of a wrapper, merging this part's attributes and classes onto it. |
| as | — | AsTag | ComponentThe element or component to render. |
| loop | — | booleanWraps keyboard navigation from the last item to the first. |
| size | — | MenuSizeItem size, from |
| Event | Payload and description |
|---|---|
| entryFocus | [event: Event]Fires when focus enters the menu. Call |
| escapeKeyDown | [event: KeyboardEvent]Fires on Escape. Call |
| pointerDownOutside | [event: PointerDownOutsideEvent]Fires on a pointer press outside. Call |
| focusOutside | [event: FocusOutsideEvent]Fires when focus moves outside. Call |
| interactOutside | [event: PointerDownOutsideEvent | FocusOutsideEvent]Fires on any press or focus outside. Call |
| openAutoFocus | [event: Event]Fires when focus moves into the panel on open. Call |
| closeAutoFocus | [event: Event]Fires when focus returns to the trigger on close. Call |
| Slot | Scope and description |
|---|---|
| default | {}The submenu's items. |
MenuSubTrigger
| Prop | Default | Type and description |
|---|---|---|
| graceDuration | — | numberHow long, in milliseconds, the pointer has to reach the submenu after leaving this item. While it heads there, hovering other items keeps the submenu open. |
| disabled | — | booleanDisables the item: it is skipped by the keyboard and cannot be chosen. |
| textValue | — | stringText used for typeahead instead of the item's text content. |
| asChild | — | booleanRender the single child instead of a wrapper, merging this part's attributes and classes onto it. |
| as | — | AsTag | ComponentThe element or component to render. |
| inset | — | booleanIndents the text to line up with items that have an indicator. |
| Slot | Scope and description |
|---|---|
| default | {}The label of the item that opens the submenu. |
Props
- contextMenu
booleanOpens the menu at the pointer on right-click, and on touch screens after a long press, instead of on click.- target
true string | boolean | ElementThe element the menu attaches to:truefor the element it is placed in, a CSS selector or an element for another one,falsefor none, when it is opened only from code.- noParentEvent
booleanLeaves the target without listeners, so onlyv-modeland the exposed methods open the menu. The target still positions it.- anchor
"top left" | "top middle" | "top right" | "top start" | "top end" | "center left" | "center middle" | "center right" | "center start" | "center end" | "bottom left" | "bottom middle" | "bottom right" | "bottom start" | "bottom end"The point on the target the menu is placed against, as a vertical part (top,center,bottom) and a horizontal one (left,middle,right,start,end).bottom startby default,center middlewithcover.- self
"top left" | "top middle" | "top right" | "top start" | "top end" | "center left" | "center middle" | "center right" | "center start" | "center end" | "bottom left" | "bottom middle" | "bottom right" | "bottom start" | "bottom end"The point on the menu that meets the anchor, in the same form asanchor.top startby default. Ignored withcover, which uses the anchor.- offset
[number, number]Pixels[x, y]added around the target before placing the menu, pushing it away. By default 4px on the axis where the menu sits beside its target, and[0, 0]when it opens at the pointer. Ignored withcover.- cover
booleanPlaces the menu over its target and makes it at least the target's size.- fit
booleanMakes the menu at least as wide as its target.- touchPosition
booleanOpens the menu where the target was clicked instead of at its edge.- autoClose
booleanCloses the menu on any click inside it, not only on an item. For menus with buttons or other content that is not an item.- persistent
booleanKeeps the menu open on Escape and on outside clicks. Only an item,v-modelorhide()closes it.- modal
true booleanShuts the page while the menu is open: an outside click only closes it, and the page does not scroll. A scrim takes the first outside click so nothing under it is activated.- maxHeight
stringThe menu's maximum height as a CSS length. Past it the menu scrolls.- maxWidth
stringThe menu's maximum width as a CSS length.- size
MenuSizeItem size, from 28px forxsto 48px forxl, with text, icons and padding to match. Submenus follow it.- modelValue
false booleanWhether the menu is open, bound withv-model.
Emits
- update:modelValue
[value: boolean]Fires when the menu opens or closes.
Slots
- default
{}The items, labels, separators and submenus, or any other content.
Exposed
- show
(event?: Event | undefined) => voidOpens the menu. Given a mouse event andtouch-positionorcontext-menu, opens it at the event's position.- hide
() => voidCloses the menu.- toggle
(event?: Event | undefined) => voidOpens the menu if it is closed, closes it otherwise.
Props
- asChild
booleanRender the single child instead of a wrapper, merging this part's attributes and classes onto it.- as
"button" AsTag | ComponentThe element or component to render; abuttonby default.
Slots
- default
{}The button that opens theMenuplaced next to this part, usually aButtonwithas-child.
Props
- disabled
booleanDisables the item: it is skipped by the keyboard and cannot be chosen.- textValue
stringText used for typeahead instead of the item's text content.- asChild
booleanRender the single child instead of a wrapper, merging this part's attributes and classes onto it.- as
AsTag | ComponentThe element or component to render.- inset
booleanIndents the text to line up with items that have an indicator.- color
MenuItemColor | (string & {})Colour role the item, its icon and its hover layer are drawn in, such asdestructivefor actions that delete or cannot be undone. Any other name picks up a colour you declare on[data-slot][data-color="<name>"].
Emits
- select
[event: Event]Fires when the item is chosen by click or keyboard. Callevent.preventDefault()to keep the menu open.
Slots
- default
{}The label, with an optional leading icon and aMenuShortcut.
Props
- modelValue
CheckedStateWhether it is checked, bound withv-model.- disabled
booleanDisables the item: it is skipped by the keyboard and cannot be chosen.- textValue
stringText used for typeahead instead of the item's text content.- asChild
booleanRender the single child instead of a wrapper, merging this part's attributes and classes onto it.- as
AsTag | ComponentThe element or component to render.
Emits
- select
[event: Event]Fires when the item is chosen by click or keyboard. Callevent.preventDefault()to keep the menu open.- update:modelValue
[payload: boolean]Fires when the item is toggled.
Slots
- indicator-icon
{}The icon shown while checked, a check by default.- default
{}The label.
Props
- value*
AcceptableValueThe value this item puts in the group'sv-model.- disabled
booleanDisables the item: it is skipped by the keyboard and cannot be chosen.- textValue
stringText used for typeahead instead of the item's text content.- asChild
booleanRender the single child instead of a wrapper, merging this part's attributes and classes onto it.- as
AsTag | ComponentThe element or component to render.
Emits
- select
[event: Event]Fires when the item is chosen by click or keyboard. Callevent.preventDefault()to keep the menu open.
Slots
- indicator-icon
{}The icon shown while checked, a dot by default.- default
{}The label.
Props
- open
booleanWhether it is open, bound withv-model:open.
Emits
- update:open
[payload: boolean]Fires when it opens or closes.
Slots
- default
{}AMenuSubTriggerand aMenuSubContent.
Props
- asChild
booleanRender the single child instead of a wrapper, merging this part's attributes and classes onto it.- as
AsTag | ComponentThe element or component to render.
Slots
- default
{}Related items.
Props
- asChild
booleanRender the single child instead of a wrapper, merging this part's attributes and classes onto it.- as
AsTag | ComponentThe element or component to render.- inset
booleanIndents the text to line up with items that have an indicator.
Slots
- default
{}The label text.
Props
- modelValue
AcceptableValueThe value of the checked item, bound withv-model.- asChild
booleanRender the single child instead of a wrapper, merging this part's attributes and classes onto it.- as
AsTag | ComponentThe element or component to render.
Emits
- update:modelValue
[payload: AcceptableValue]Fires when another item is checked.
Slots
- default
{}The radio items.
Props
- asChild
booleanRender the single child instead of a wrapper, merging this part's attributes and classes onto it.- as
AsTag | ComponentThe element or component to render.
Slots
- default
{}The key combination, for display only. It does not register the shortcut.
Props
- forceMount
booleanKeeps the panel mounted while closed, for animating it with a JavaScript library.- memoDependencies
unknown[]Values that should re-run the position update when they change.- sideOffset
numberDistance in pixels from the trigger.- sideFlip
booleanFlips to the opposite side when the preferred one would overflow.- alignOffset
numberOffset in pixels from thealignposition.- alignFlip
booleanFlips the alignment when it would overflow.- avoidCollisions
booleanKeeps the panel inside the collision boundary by flipping and shifting it.- collisionBoundary
Element | (Element | null)[] | nullThe element or elements used as the collision boundary. The viewport by default.- collisionPadding
number | Partial<Record<"top" | "right" | "bottom" | "left", number>>Distance in pixels from the boundary edges where collisions start.- arrowPadding
numberPadding between an arrow and the panel's corners.- hideShiftedArrow
booleanHides an arrow when the panel is shifted so far that the arrow would not point at the trigger.- sticky
"partial" | "always"partialkeeps the panel attached to the trigger while scrolling;alwaysalso lets it detach from the trigger to stay in the boundary.- hideWhenDetached
booleanHides the panel when the trigger is scrolled out of view.- positionStrategy
"absolute" | "fixed"The CSS position used to place the panel.- updatePositionStrategy
"always" | "optimized"alwaysrecomputes the position on every animation frame instead of only on layout changes.- disableUpdateOnLayoutShift
booleanStops recomputing the position when the layout shifts.- prioritizePosition
booleanKeeps the preferred side and alignment and lets the panel overflow instead of flipping.- reference
ReferenceElementA virtual element to position against instead of the trigger.- asChild
booleanRender the single child instead of a wrapper, merging this part's attributes and classes onto it.- as
AsTag | ComponentThe element or component to render.- loop
booleanWraps keyboard navigation from the last item to the first.- size
MenuSizeItem size, fromxstoxl. Defaults to the size of the menu the submenu opens from.
Emits
- entryFocus
[event: Event]Fires when focus enters the menu. CallpreventDefault()to keep the first item from being highlighted.- escapeKeyDown
[event: KeyboardEvent]Fires on Escape. CallpreventDefault()to keep it open.- pointerDownOutside
[event: PointerDownOutsideEvent]Fires on a pointer press outside. CallpreventDefault()to keep it open.- focusOutside
[event: FocusOutsideEvent]Fires when focus moves outside. CallpreventDefault()to keep it open.- interactOutside
[event: PointerDownOutsideEvent | FocusOutsideEvent]Fires on any press or focus outside. CallpreventDefault()to keep it open.- openAutoFocus
[event: Event]Fires when focus moves into the panel on open. CallpreventDefault()to keep focus where it is.- closeAutoFocus
[event: Event]Fires when focus returns to the trigger on close. CallpreventDefault()to keep focus where it is.
Slots
- default
{}The submenu's items.
Props
- graceDuration
numberHow long, in milliseconds, the pointer has to reach the submenu after leaving this item. While it heads there, hovering other items keeps the submenu open.300by default. Needsreka-ui2.11 or later.- disabled
booleanDisables the item: it is skipped by the keyboard and cannot be chosen.- textValue
stringText used for typeahead instead of the item's text content.- asChild
booleanRender the single child instead of a wrapper, merging this part's attributes and classes onto it.- as
AsTag | ComponentThe element or component to render.- inset
booleanIndents the text to line up with items that have an indicator.
Slots
- default
{}The label of the item that opens the submenu.
Data attributes
| data-slot | Attributes | Description |
|---|---|---|
| menu | data-state, data-size | The menu's panel, with role="menu". data-size is its size, xs to xl. |
| menu-scrim | — | The transparent layer under a modal menu that takes the first outside click. |
| menu-trigger | data-state, aria-expanded | The element a sibling Menu attaches to, when MenuTrigger is used; with as-child the child carries it. |
| menu-item | data-highlighted, data-disabled, data-inset, data-color | An item. data-color carries its color. |
| menu-checkbox-item | data-state, data-highlighted, data-disabled | A checkbox item. data-state is checked, unchecked or indeterminate. |
| menu-radio-item | data-state, data-highlighted, data-disabled | A radio item. |
| menu-label | data-inset | A label for the items after it. |
| menu-separator | — | A line between groups. |
| menu-shortcut | — | A key combination at the end of an item. |
| menu-sub-trigger | data-state, data-highlighted, data-inset | The item that opens a submenu. |
| menu-sub-content | data-state, data-side, data-size | A submenu's panel. |