DropdownMenu
<script setup lang="ts">
import {
DropdownMenuArrow,
DropdownMenuCheckboxItem,
DropdownMenuContent,
DropdownMenuItem,
DropdownMenuItemIndicator,
DropdownMenuLabel,
DropdownMenuPortal,
DropdownMenuRadioGroup,
DropdownMenuRadioItem,
DropdownMenuRoot,
DropdownMenuSeparator,
DropdownMenuSub,
DropdownMenuSubContent,
DropdownMenuSubTrigger,
DropdownMenuTrigger,
} from 'akar';
import { ref } from 'vue';
import './styles.css';
const toggleState = ref(false);
const checkboxOne = ref(false);
const checkboxTwo = ref(false);
const person = ref('pedro');
function handleSelect() {
// eslint-disable-next-line no-alert
alert('hello!');
}
</script>
<template>
<div class="akar-demo akar-demo-DropdownMenu">
<DropdownMenuRoot v-model:open="toggleState">
<DropdownMenuTrigger
class="IconButton"
aria-label="Customise options"
>
<PIcon name="i-lucide-menu" />
</DropdownMenuTrigger>
<DropdownMenuPortal>
<DropdownMenuContent
class="DropdownMenuContent"
:side-offset="5"
>
<DropdownMenuItem
value="New Tab"
class="DropdownMenuItem"
@select="handleSelect"
>
New Tab
<div
class="RightSlot"
>
⌘+T
</div>
</DropdownMenuItem>
<DropdownMenuSub>
<DropdownMenuSubTrigger
value="more toolsz"
class="DropdownMenuSubTrigger"
>
More Tools
<div
class="RightSlot"
>
<PIcon name="i-lucide-chevron-right" />
</div>
</DropdownMenuSubTrigger>
<DropdownMenuPortal>
<DropdownMenuSubContent
class="DropdownMenuContent"
:side-offset="2"
:align-offset="-5"
>
<DropdownMenuItem
class="DropdownMenuItem"
>
Save Page As…
<div
class="RightSlot"
>
⌘+S
</div>
</DropdownMenuItem>
<DropdownMenuItem
class="DropdownMenuItem"
>
Create Shortcut…
</DropdownMenuItem>
<DropdownMenuItem
class="DropdownMenuItem"
>
Name Window…
</DropdownMenuItem>
<DropdownMenuSeparator class="DropdownMenuSeparator" />
<DropdownMenuItem
class="DropdownMenuItem"
>
Developer Tools
</DropdownMenuItem>
</DropdownMenuSubContent>
</DropdownMenuPortal>
</DropdownMenuSub>
<DropdownMenuItem
value="New Window"
class="DropdownMenuItem"
>
New Window
<div
class="RightSlot"
>
⌘+N
</div>
</DropdownMenuItem>
<DropdownMenuItem
value="New Private Window"
class="DropdownMenuItem"
disabled
>
New Private Window
<div
class="RightSlot"
>
⇧+⌘+N
</div>
</DropdownMenuItem>
<DropdownMenuSub>
<DropdownMenuSubTrigger
value="more tools"
class="DropdownMenuSubTrigger"
>
More Tools
<div
class="RightSlot"
>
<PIcon name="i-lucide-chevron-right" />
</div>
</DropdownMenuSubTrigger>
<DropdownMenuPortal>
<DropdownMenuSubContent
class="DropdownMenuContent"
:side-offset="2"
:align-offset="-5"
>
<DropdownMenuItem
class="DropdownMenuItem"
>
Save Page As…
<div
class="RightSlot"
>
⌘+S
</div>
</DropdownMenuItem>
<DropdownMenuItem
class="DropdownMenuItem"
>
Create Shortcut…
</DropdownMenuItem>
<DropdownMenuItem
class="DropdownMenuItem"
>
Name Window…
</DropdownMenuItem>
<DropdownMenuSeparator class="DropdownMenuSeparator" />
<DropdownMenuItem
class="DropdownMenuItem"
>
Developer Tools
</DropdownMenuItem>
<DropdownMenuSub>
<DropdownMenuSubTrigger
value="more toolsz"
class="DropdownMenuSubTrigger"
>
More Tools
<div
class="RightSlot"
>
<PIcon name="i-lucide-chevron-right" />
</div>
</DropdownMenuSubTrigger>
<DropdownMenuPortal>
<DropdownMenuSubContent
class="DropdownMenuContent"
:side-offset="2"
:align-offset="-5"
>
<DropdownMenuItem
class="DropdownMenuItem"
>
Save Page As…
<div
class="RightSlot"
>
⌘+S
</div>
</DropdownMenuItem>
<DropdownMenuItem
class="DropdownMenuItem"
>
Create Shortcut…
</DropdownMenuItem>
<DropdownMenuItem
class="DropdownMenuItem"
>
Name Window…
</DropdownMenuItem>
<DropdownMenuSeparator class="DropdownMenuSeparator" />
<DropdownMenuItem
class="DropdownMenuItem"
>
Developer Tools
</DropdownMenuItem>
<DropdownMenuSub>
<DropdownMenuSubTrigger
value="more toolsz"
class="DropdownMenuSubTrigger"
>
More Tools
<div
class="RightSlot"
>
<PIcon name="i-lucide-chevron-right" />
</div>
</DropdownMenuSubTrigger>
<DropdownMenuPortal>
<DropdownMenuSubContent
class="DropdownMenuContent"
:side-offset="2"
:align-offset="-5"
>
<DropdownMenuItem
class="DropdownMenuItem"
>
Save Page As…
<div
class="RightSlot"
>
⌘+S
</div>
</DropdownMenuItem>
<DropdownMenuItem
class="DropdownMenuItem"
>
Create Shortcut…
</DropdownMenuItem>
<DropdownMenuItem
class="DropdownMenuItem"
>
Name Window…
</DropdownMenuItem>
<DropdownMenuSeparator class="DropdownMenuSeparator" />
<DropdownMenuItem
class="DropdownMenuItem"
>
Developer Tools
</DropdownMenuItem>
</DropdownMenuSubContent>
</DropdownMenuPortal>
</DropdownMenuSub>
</DropdownMenuSubContent>
</DropdownMenuPortal>
</DropdownMenuSub>
<DropdownMenuItem
class="DropdownMenuItem"
>
Developer Tools
</DropdownMenuItem>
</DropdownMenuSubContent>
</DropdownMenuPortal>
</DropdownMenuSub>
<DropdownMenuSeparator class="DropdownMenuSeparator" />
<DropdownMenuCheckboxItem
v-model="checkboxOne"
class="DropdownMenuItem"
>
<DropdownMenuItemIndicator class="DropdownMenuItemIndicator">
<PIcon name="i-lucide-check" />
</DropdownMenuItemIndicator>
Show Bookmarks
<div
class="RightSlot"
>
⌘+B
</div>
</DropdownMenuCheckboxItem>
<DropdownMenuCheckboxItem
v-model="checkboxTwo"
class="DropdownMenuItem"
>
<DropdownMenuItemIndicator class="DropdownMenuItemIndicator">
<PIcon name="i-lucide-check" />
</DropdownMenuItemIndicator>
Show Full URLs
</DropdownMenuCheckboxItem>
<DropdownMenuSeparator class="DropdownMenuSeparator" />
<DropdownMenuLabel class="DropdownMenuLabel">
People
</DropdownMenuLabel>
<DropdownMenuRadioGroup v-model="person">
<DropdownMenuRadioItem
class="DropdownMenuItem"
value="pedro"
>
<DropdownMenuItemIndicator class="DropdownMenuItemIndicator">
<PIcon name="i-lucide-circle" />
</DropdownMenuItemIndicator>
Pedro Duarte
</DropdownMenuRadioItem>
<DropdownMenuRadioItem
class="DropdownMenuItem"
value="colm"
>
<DropdownMenuItemIndicator class="DropdownMenuItemIndicator">
<PIcon name="i-lucide-circle" />
</DropdownMenuItemIndicator>
Colm Tuite
</DropdownMenuRadioItem>
</DropdownMenuRadioGroup>
<DropdownMenuArrow class="DropdownMenuArrow" />
</DropdownMenuContent>
</DropdownMenuPortal>
</DropdownMenuRoot>
</div>
</template>@import '../_colors/black-alpha.css';
@import '../_colors/mauve.css';
@import '../_colors/grass.css';
@scope (.akar-demo-DropdownMenu) {
/* reset */
button {
all: unset;
}
.DropdownMenuContent,
.DropdownMenuSubContent {
min-width: 220px;
background-color: white;
border-radius: 6px;
padding: 5px;
box-shadow:
0px 10px 38px -10px rgba(22, 23, 24, 0.35),
0px 10px 20px -15px rgba(22, 23, 24, 0.2);
animation-duration: 400ms;
animation-timing-function: cubic-bezier(0.16, 1, 0.3, 1);
will-change: transform, opacity;
}
.DropdownMenuContent[data-side='top'],
.DropdownMenuSubContent[data-side='top'] {
animation-name: slideDownAndFade;
}
.DropdownMenuContent[data-side='right'],
.DropdownMenuSubContent[data-side='right'] {
animation-name: slideLeftAndFade;
}
.DropdownMenuContent[data-side='bottom'],
.DropdownMenuSubContent[data-side='bottom'] {
animation-name: slideUpAndFade;
}
.DropdownMenuContent[data-side='left'],
.DropdownMenuSubContent[data-side='left'] {
animation-name: slideRightAndFade;
}
.DropdownMenuItem,
.DropdownMenuCheckboxItem,
.DropdownMenuRadioItem,
.DropdownMenuSubTrigger {
font-size: 13px;
line-height: 1;
color: var(--grass-11);
border-radius: 3px;
display: flex;
align-items: center;
height: 25px;
padding: 0 5px;
position: relative;
padding-left: 25px;
user-select: none;
outline: none;
}
.DropdownMenuSubTrigger[data-state='open'] {
background-color: var(--grass-4);
color: var(--grass-11);
}
.DropdownMenuItem[data-disabled],
.DropdownMenuCheckboxItem[data-disabled],
.DropdownMenuRadioItem[data-disabled],
.DropdownMenuSubTrigger[data-disabled] {
color: var(--mauve-8);
pointer-events: none;
}
.DropdownMenuItem[data-highlighted],
.DropdownMenuCheckboxItem[data-highlighted],
.DropdownMenuRadioItem[data-highlighted],
.DropdownMenuSubTrigger[data-highlighted] {
background-color: var(--grass-9);
color: var(--grass-1);
}
.DropdownMenuLabel {
padding-left: 25px;
font-size: 12px;
line-height: 25px;
color: var(--mauve-11);
}
.DropdownMenuSeparator {
height: 1px;
background-color: var(--grass-6);
margin: 5px;
}
.DropdownMenuItemIndicator {
position: absolute;
left: 0;
width: 25px;
display: inline-flex;
align-items: center;
justify-content: center;
}
.DropdownMenuArrow {
fill: white;
}
.IconButton {
font-family: inherit;
border-radius: 100%;
height: 35px;
width: 35px;
display: inline-flex;
align-items: center;
justify-content: center;
color: var(--grass-11);
background-color: white;
box-shadow: 0 2px 10px var(--black-a7);
}
.IconButton:hover {
background-color: var(--grass-3);
}
.IconButton:focus {
box-shadow: 0 0 0 2px black;
}
.RightSlot {
margin-left: auto;
padding-left: 20px;
color: var(--mauve-11);
}
[data-highlighted] > .RightSlot {
color: white;
}
[data-disabled] .RightSlot {
color: var(--mauve-8);
}
@keyframes slideUpAndFade {
from {
opacity: 0;
transform: translateY(2px);
}
to {
opacity: 1;
transform: translateY(0);
}
}
@keyframes slideRightAndFade {
from {
opacity: 0;
transform: translateX(-2px);
}
to {
opacity: 1;
transform: translateX(0);
}
}
@keyframes slideDownAndFade {
from {
opacity: 0;
transform: translateY(-2px);
}
to {
opacity: 1;
transform: translateY(0);
}
}
@keyframes slideLeftAndFade {
from {
opacity: 0;
transform: translateX(2px);
}
to {
opacity: 1;
transform: translateX(0);
}
}
}Features
- Can be controlled or uncontrolled.
- Supports submenus with configurable reading direction.
- Supports items, labels, groups of items.
- Supports checkable items (single or multiple) with optional indeterminate state.
- Supports modal and non-modal modes.
- Customize side, alignment, offsets, collision handling.
- Optionally render a pointing arrow.
- Focus is fully managed.
- Full keyboard navigation.
- Typeahead support.
- Dismissing and layering behavior is highly customizable.
Installation
Install the component from your command line.
pnpm add akar
yarn add akar
npm install akar
bun add akar
Anatomy
Import all parts and piece them together.
<script setup lang="ts">
import {
DropdownMenuArrow,
DropdownMenuCheckboxItem,
DropdownMenuContent,
DropdownMenuFilter,
DropdownMenuGroup,
DropdownMenuItem,
DropdownMenuItemIndicator,
DropdownMenuLabel,
DropdownMenuPortal,
DropdownMenuRadioGroup,
DropdownMenuRadioItem,
DropdownMenuRoot,
DropdownMenuSeparator,
DropdownMenuSub,
DropdownMenuSubContent,
DropdownMenuSubTrigger,
DropdownMenuTrigger,
} from 'akar';
</script>
<template>
<DropdownMenuRoot>
<DropdownMenuTrigger />
<DropdownMenuPortal>
<DropdownMenuContent>
<DropdownMenuFilter />
<DropdownMenuLabel />
<DropdownMenuItem />
<DropdownMenuGroup>
<DropdownMenuItem />
</DropdownMenuGroup>
<DropdownMenuCheckboxItem>
<DropdownMenuItemIndicator />
</DropdownMenuCheckboxItem>
<DropdownMenuRadioGroup>
<DropdownMenuRadioItem>
<DropdownMenuItemIndicator />
</DropdownMenuRadioItem>
</DropdownMenuRadioGroup>
<DropdownMenuSub>
<DropdownMenuSubTrigger />
<DropdownMenuPortal>
<DropdownMenuSubContent />
</DropdownMenuPortal>
</DropdownMenuSub>
<DropdownMenuSeparator />
<DropdownMenuArrow />
</DropdownMenuContent>
</DropdownMenuPortal>
</DropdownMenuRoot>
</template>
API Reference
Root
Contains all the parts of a dropdown menu.
| Prop | Default | Type |
|---|---|---|
defaultOpen | booleanThe open state of the dropdown menu when it is initially rendered. Use when you do not need to control its open state. | |
dir | "ltr" | "rtl"The reading direction of the combobox when applicable. If omitted, inherits globally from | |
modal | true | booleanThe modality of the dropdown menu. When set to |
open | booleanThe controlled open state of the menu. Can be used as |
| Event | Payload |
|---|---|
update:open | payload: boolean |
| Slot (default) | Payload |
|---|---|
open | booleanCurrent open state |
Trigger
The button that toggles the dropdown menu. By default, the DropdownMenuContent will position itself against the trigger.
| Prop | Default | Type |
|---|---|---|
as | "button" | AsTag | ComponentThe element or component this component should render as. Can be overwritten by |
asChild | booleanChange the default rendered element for the one passed as a child, merging their props and behavior. Read our Composition guide for more details. | |
disabled | booleanWhen |
| Data attribute | Value |
|---|---|
[data-state] | "open" | "closed" |
[data-disabled] | Present when disabled |
Portal
When used, portals the content part into the body.
| Prop | Default | Type |
|---|---|---|
defer | booleanDefer the resolving of a Teleport target until other parts of the application have mounted (requires Vue 3.5.0+) | |
disabled | booleanDisable teleport and render the component inline | |
forceMount | booleanUsed to force mounting when more control is needed. Useful when controlling animation with Vue animation libraries. | |
to | string | HTMLElementVue native teleport component prop |
Content
The component that pops out when the dropdown menu is open.
| Prop | Default | Type |
|---|---|---|
align | "center" | "start" | "center" | "end"The preferred alignment against the trigger. May change when collisions occur. |
alignFlip | true | booleanFlip alignment when colliding with boundary.
May only occur when |
alignOffset | 0 | numberAn offset in pixels from the |
arrowPadding | 0 | numberThe padding between the arrow and the edges of the content. If your content has border-radius, this will prevent it from overflowing the corners. |
as | "div" | AsTag | ComponentThe element or component this component should render as. Can be overwritten by |
asChild | booleanChange the default rendered element for the one passed as a child, merging their props and behavior. Read our Composition guide for more details. | |
avoidCollisions | true | booleanWhen |
collisionBoundary | [] | Element | (Element | null)[] | nullThe element used as the collision boundary. By default this is the viewport, though you can provide additional element(s) to be included in this check. |
collisionPadding | 0 | number | Partial<Record<"top" | "right" | "bottom" | "left", number>>The distance in pixels from the boundary edges where collision detection should occur. Accepts a number (same for all sides), or a partial padding object, for example: . |
disableUpdateOnLayoutShift | false | booleanWhether to disable the update position for the content when the layout shifted. |
forceMount | booleanUsed to force mounting when more control is needed. Useful when controlling animation with Vue animation libraries. | |
hideShiftedArrow | true | booleanWhen |
hideWhenDetached | false | booleanWhether to hide the content when the trigger becomes fully occluded. |
loop | false | booleanWhen |
memoDependencies | unknown[]Reactive dependencies that should invalidate the memoized content subtree. | |
positionStrategy | "fixed" | "absolute"The type of CSS position property to use. | |
prioritizePosition | false | booleanForce content to be position within the viewport. Might overlap the reference element, which may not be desired. |
reference | ReferenceElementThe custom element or virtual element that will be set as the reference to position the floating element. If provided, it will replace the default anchor element. | |
side | "bottom" | "top" | "right" | "bottom" | "left"The preferred side of the trigger to render against when open. Will be reversed when collisions occur and avoidCollisions is enabled. |
sideFlip | true | booleanFlip to the opposite side when colliding with boundary. |
sideOffset | 0 | numberThe distance in pixels from the trigger. |
sticky | "partial" | "partial" | "always"The sticky behavior on the align axis. |
updatePositionStrategy | 'optimized' | "always" | "optimized"Strategy to update the position of the floating element on every animation frame. |
| Event | Payload |
|---|---|
closeAutoFocus | event: EventEvent handler called when auto-focusing on close. Can be prevented. |
escapeKeyDown | event: KeyboardEventEvent handler called when the escape key is down. Can be prevented. |
focusOutside | event: FocusOutsideEventEvent handler called when the focus moves outside of the |
interactOutside | event: PointerDownOutsideEvent | FocusOutsideEventEvent handler called when an interaction happens outside the |
openAutoFocus | event: Event |
pointerDownOutside | event: PointerDownOutsideEventEvent handler called when a |
| Data attribute | Value |
|---|---|
[data-state] | "open" | "closed" |
[data-side] | "left" | "right" | "bottom" | "top" |
[data-align] | "start" | "end" | "center" |
[data-orientation] | "vertical" | "horizontal" |
| CSS variable | Description |
|---|---|
--akar-dropdown-menu-content-transform-origin | The transform-origin computed from the content and arrow positions/offsets |
--akar-dropdown-menu-content-available-width | The remaining width between the trigger and the boundary edge |
--akar-dropdown-menu-content-available-height | The remaining height between the trigger and the boundary edge |
--akar-dropdown-menu-trigger-width | The width of the trigger |
--akar-dropdown-menu-trigger-height | The height of the trigger |
Filter
An optional search input inside DropdownMenuContent or DropdownMenuSubContent. It integrates text input with the menu's keyboard navigation.
| Prop | Default | Type |
|---|---|---|
as | "input" | AsTag | ComponentThe element or component this component should render as. Can be overwritten by |
asChild | booleanChange the default rendered element for the one passed as a child, merging their props and behavior. Read our Composition guide for more details. | |
autoFocus | booleanFocus on element when mounted. | |
disabled | booleanWhen | |
modelValue | stringThe controlled value of the filter. Can be binded with v-model. |
| Event | Payload |
|---|---|
update:modelValue | string |
| Slot (default) | Payload |
|---|---|
modelValue | stringCurrent input values |
| Data attribute | Value |
|---|---|
[data-disabled] | Present when disabled |
Arrow
An optional arrow element to render alongside the dropdown menu. This can be used to help visually link the trigger with the DropdownMenuContent. Must be rendered inside DropdownMenuContent.
| Prop | Default | Type |
|---|---|---|
as | "svg" | AsTag | ComponentThe element or component this component should render as. Can be overwritten by |
asChild | booleanChange the default rendered element for the one passed as a child, merging their props and behavior. Read our Composition guide for more details. | |
height | 5 | numberThe height of the arrow in pixels. |
rounded | false | booleanWhen |
width | 10 | numberThe width of the arrow in pixels. |
Item
The component that contains the dropdown menu items.
| Prop | Default | Type |
|---|---|---|
as | "div" | AsTag | ComponentThe element or component this component should render as. Can be overwritten by |
asChild | booleanChange the default rendered element for the one passed as a child, merging their props and behavior. Read our Composition guide for more details. | |
disabled | booleanWhen | |
textValue | stringOptional text used for typeahead purposes. By default the typeahead behavior will use the Use this when the content is complex, or you have non-textual content inside. |
| Event | Payload |
|---|---|
select | event: EventEvent handler called when the user selects an item (via mouse or keyboard). Calling |
| Data attribute | Value |
|---|---|
[data-orientation] | "vertical" | "horizontal" |
[data-highlighted] | Present when highlighted |
[data-disabled] | Present when disabled |
Group
Used to group multiple DropdownMenuItems.
| Prop | Default | Type |
|---|---|---|
as | "div" | AsTag | ComponentThe element or component this component should render as. Can be overwritten by |
asChild | booleanChange the default rendered element for the one passed as a child, merging their props and behavior. Read our Composition guide for more details. |
Label
Used to render a label. It won't be focusable using arrow keys.
| Prop | Default | Type |
|---|---|---|
as | "div" | AsTag | ComponentThe element or component this component should render as. Can be overwritten by |
asChild | booleanChange the default rendered element for the one passed as a child, merging their props and behavior. Read our Composition guide for more details. |
CheckboxItem
An item that can be controlled and rendered like a checkbox.
| Prop | Default | Type |
|---|---|---|
as | "div" | AsTag | ComponentThe element or component this component should render as. Can be overwritten by |
asChild | booleanChange the default rendered element for the one passed as a child, merging their props and behavior. Read our Composition guide for more details. | |
disabled | booleanWhen | |
modelValue | false | true | "indeterminate"The controlled checked state of the item. Can be used as | |
textValue | stringOptional text used for typeahead purposes. By default the typeahead behavior will use the Use this when the content is complex, or you have non-textual content inside. |
| Event | Payload |
|---|---|
select | event: EventEvent handler called when the user selects an item (via mouse or keyboard). Calling |
update:modelValue | payload: booleanEvent handler called when the checked state changes. |
| Slot (default) | Payload |
|---|---|
checked | false | true | "indeterminate"Current checked state |
modelValue | CheckedStateCurrent modelValue state |
| Data attribute | Value |
|---|---|
[data-state] | "checked" | "unchecked" | "indeterminate" |
[data-highlighted] | Present when highlighted |
[data-disabled] | Present when disabled |
RadioGroup
Used to group multiple DropdownMenuRadioItems.
| Prop | Default | Type |
|---|---|---|
as | "div" | AsTag | ComponentThe element or component this component should render as. Can be overwritten by |
asChild | booleanChange the default rendered element for the one passed as a child, merging their props and behavior. Read our Composition guide for more details. | |
modelValue | AcceptableValueThe value of the selected item in the group. |
| Event | Payload |
|---|---|
update:modelValue | payload: AcceptableValueEvent handler called when the value changes. |
RadioItem
An item that can be controlled and rendered like a radio.
| Prop | Default | Type |
|---|---|---|
as | "div" | AsTag | ComponentThe element or component this component should render as. Can be overwritten by |
asChild | booleanChange the default rendered element for the one passed as a child, merging their props and behavior. Read our Composition guide for more details. | |
disabled | booleanWhen | |
textValue | stringOptional text used for typeahead purposes. By default the typeahead behavior will use the Use this when the content is complex, or you have non-textual content inside. | |
value* | AcceptableValueThe unique value of the item. |
| Event | Payload |
|---|---|
select | event: EventEvent handler called when the user selects an item (via mouse or keyboard). Calling |
| Slot (default) | Payload |
|---|---|
checked | booleanCurrent checked state |
| Data attribute | Value |
|---|---|
[data-state] | "checked" | "unchecked" | "indeterminate" |
[data-highlighted] | Present when highlighted |
[data-disabled] | Present when disabled |
ItemIndicator
Renders when the parent DropdownMenuCheckboxItem or DropdownMenuRadioItem is checked. You can style this element directly, or you can use it as a wrapper to put an icon into, or both.
| Prop | Default | Type |
|---|---|---|
as | "div" | AsTag | ComponentThe element or component this component should render as. Can be overwritten by |
asChild | booleanChange the default rendered element for the one passed as a child, merging their props and behavior. Read our Composition guide for more details. | |
forceMount | booleanUsed to force mounting when more control is needed. Useful when controlling animation with Vue animation libraries. |
| Data attribute | Value |
|---|---|
[data-state] | "checked" | "unchecked" | "indeterminate" |
Separator
Used to visually separate items in the dropdown menu.
| Prop | Default | Type |
|---|---|---|
as | "div" | AsTag | ComponentThe element or component this component should render as. Can be overwritten by |
asChild | booleanChange the default rendered element for the one passed as a child, merging their props and behavior. Read our Composition guide for more details. |
Sub
Contains all the parts of a submenu.
| Prop | Default | Type |
|---|---|---|
defaultOpen | booleanThe open state of the dropdown menu when it is initially rendered. Use when you do not need to control its open state. | |
open | booleanThe controlled open state of the menu. Can be used as |
| Event | Payload |
|---|---|
update:open | payload: booleanEvent handler called when the open state of the submenu changes. |
| Slot (default) | Payload |
|---|---|
open | booleanCurrent open state |
SubTrigger
An item that opens a submenu. Must be rendered inside DropdownMenuSub.
| Prop | Default | Type |
|---|---|---|
as | "div" | AsTag | ComponentThe element or component this component should render as. Can be overwritten by |
asChild | booleanChange the default rendered element for the one passed as a child, merging their props and behavior. Read our Composition guide for more details. | |
disabled | booleanWhen | |
graceDuration | 300 | numberTime in milliseconds to keep a submenu open while the pointer moves from its trigger to the submenu. |
textValue | stringOptional text used for typeahead purposes. By default the typeahead behavior will use the Use this when the content is complex, or you have non-textual content inside. |
| Data attribute | Value |
|---|---|
[data-state] | "open" | "closed" |
[data-highlighted] | Present when highlighted |
[data-disabled] | Present when disabled |
| CSS variable | Description |
|---|---|
--akar-dropdown-menu-content-transform-origin | The transform-origin computed from the content and arrow positions/offsets |
--akar-dropdown-menu-content-available-width | The remaining width between the trigger and the boundary edge |
--akar-dropdown-menu-content-available-height | The remaining height between the trigger and the boundary edge |
--akar-dropdown-menu-trigger-width | The width of the trigger |
--akar-dropdown-menu-trigger-height | The height of the trigger |
SubContent
The component that pops out when a submenu is open. Must be rendered inside DropdownMenuSub.
| Prop | Default | Type |
|---|---|---|
alignFlip | true | booleanFlip alignment when colliding with boundary.
May only occur when |
alignOffset | 0 | numberAn offset in pixels from the |
arrowPadding | 0 | numberThe padding between the arrow and the edges of the content. If your content has border-radius, this will prevent it from overflowing the corners. |
as | "div" | AsTag | ComponentThe element or component this component should render as. Can be overwritten by |
asChild | booleanChange the default rendered element for the one passed as a child, merging their props and behavior. Read our Composition guide for more details. | |
avoidCollisions | true | booleanWhen |
collisionBoundary | [] | Element | (Element | null)[] | nullThe element used as the collision boundary. By default this is the viewport, though you can provide additional element(s) to be included in this check. |
collisionPadding | 0 | number | Partial<Record<"top" | "right" | "bottom" | "left", number>>The distance in pixels from the boundary edges where collision detection should occur. Accepts a number (same for all sides), or a partial padding object, for example: . |
disableUpdateOnLayoutShift | false | booleanWhether to disable the update position for the content when the layout shifted. |
forceMount | booleanUsed to force mounting when more control is needed. Useful when controlling animation with Vue animation libraries. | |
hideShiftedArrow | true | booleanWhen |
hideWhenDetached | false | booleanWhether to hide the content when the trigger becomes fully occluded. |
loop | false | booleanWhen |
memoDependencies | unknown[]Reactive dependencies that should invalidate the memoized content subtree. | |
positionStrategy | "fixed" | "absolute"The type of CSS position property to use. | |
prioritizePosition | false | booleanForce content to be position within the viewport. Might overlap the reference element, which may not be desired. |
reference | ReferenceElementThe custom element or virtual element that will be set as the reference to position the floating element. If provided, it will replace the default anchor element. | |
sideFlip | true | booleanFlip to the opposite side when colliding with boundary. |
sideOffset | 0 | numberThe distance in pixels from the trigger. |
sticky | "partial" | "partial" | "always"The sticky behavior on the align axis. |
updatePositionStrategy | 'optimized' | "always" | "optimized"Strategy to update the position of the floating element on every animation frame. |
| Event | Payload |
|---|---|
closeAutoFocus | event: EventEvent handler called when auto-focusing on close. Can be prevented. |
entryFocus | event: Event |
escapeKeyDown | event: KeyboardEventEvent handler called when the escape key is down. Can be prevented. |
focusOutside | event: FocusOutsideEventEvent handler called when the focus moves outside of the |
interactOutside | event: PointerDownOutsideEvent | FocusOutsideEventEvent handler called when an interaction happens outside the |
openAutoFocus | event: Event |
pointerDownOutside | event: PointerDownOutsideEventEvent handler called when a |
| Data attribute | Value |
|---|---|
[data-state] | "open" | "closed" |
[data-side] | "left" | "right" | "bottom" | "top" |
[data-align] | "start" | "end" | "center" |
[data-orientation] | "vertical" | "horizontal" |
Examples
With submenus
You can create submenus by using DropdownMenuSub in combination with its parts.
<script setup lang="ts">
import {
DropdownMenuArrow,
DropdownMenuContent,
DropdownMenuItem,
DropdownMenuPortal,
DropdownMenuRoot,
DropdownMenuSeparator,
DropdownMenuSub,
DropdownMenuSubContent,
DropdownMenuSubTrigger,
DropdownMenuTrigger,
} from 'akar'
</script>
<template>
<DropdownMenuRoot>
<DropdownMenuTrigger>…</DropdownMenuTrigger>
<DropdownMenuPortal>
<DropdownMenuContent>
<DropdownMenuItem>…</DropdownMenuItem>
<DropdownMenuItem>…</DropdownMenuItem>
<DropdownMenuSeparator />
<DropdownMenuSub>
<DropdownMenuSubTrigger>Sub menu →</DropdownMenuSubTrigger>
<DropdownMenuPortal>
<DropdownMenuSubContent>
<DropdownMenuItem>Sub menu item</DropdownMenuItem>
<DropdownMenuItem>Sub menu item</DropdownMenuItem>
<DropdownMenuArrow />
</DropdownMenuSubContent>
</DropdownMenuPortal>
</DropdownMenuSub>
<DropdownMenuSeparator />
<DropdownMenuItem>…</DropdownMenuItem>
</DropdownMenuContent>
</DropdownMenuPortal>
</DropdownMenuRoot>
</template>
With disabled items
You can add special styles to disabled items via the data-disabled attribute.
<script setup lang="ts">
import {
DropdownMenuContent,
DropdownMenuItem,
DropdownMenuPortal,
DropdownMenuRoot,
DropdownMenuTrigger,
} from 'akar'
</script>
<template>
<DropdownMenuRoot>
<DropdownMenuTrigger>…</DropdownMenuTrigger>
<DropdownMenuPortal>
<DropdownMenuContent>
<DropdownMenuItem
class="DropdownMenuItem"
disabled
>
…
</DropdownMenuItem>
<DropdownMenuItem class="DropdownMenuItem">
…
</DropdownMenuItem>
</DropdownMenuContent>
</DropdownMenuPortal>
</DropdownMenuRoot>
</template>
/* styles.css */
.DropdownMenuItem[data-disabled] {
color: gainsboro;
}
With separators
Use the Separator part to add a separator between items.
<script setup lang="ts">
import {
DropdownMenuContent,
DropdownMenuItem,
DropdownMenuPortal,
DropdownMenuRoot,
DropdownMenuSeparator,
DropdownMenuTrigger,
} from 'akar'
</script>
<template>
<DropdownMenuRoot>
<DropdownMenuTrigger>…</DropdownMenuTrigger>
<DropdownMenuPortal>
<DropdownMenuContent>
<DropdownMenuItem>…</DropdownMenuItem>
<DropdownMenuSeparator />
<DropdownMenuItem>…</DropdownMenuItem>
<DropdownMenuSeparator />
<DropdownMenuItem>…</DropdownMenuItem>
</DropdownMenuContent>
</DropdownMenuPortal>
</DropdownMenuRoot>
</template>
With labels
Use the Label part to help label a section.
<script setup lang="ts">
import {
DropdownMenuContent,
DropdownMenuItem,
DropdownMenuLabel,
DropdownMenuPortal,
DropdownMenuRoot,
DropdownMenuTrigger,
} from 'akar'
</script>
<template>
<DropdownMenuRoot>
<DropdownMenuTrigger>…</DropdownMenuTrigger>
<DropdownMenuPortal>
<DropdownMenuContent>
<DropdownMenuLabel>Label</DropdownMenuLabel>
<DropdownMenuItem>…</DropdownMenuItem>
<DropdownMenuItem>…</DropdownMenuItem>
<DropdownMenuItem>…</DropdownMenuItem>
</DropdownMenuContent>
</DropdownMenuPortal>
</DropdownMenuRoot>
</template>
With checkbox items
Use the CheckboxItem part to add an item that can be checked.
<script setup lang="ts">
import { Icon } from '@iconify/vue'
import {
DropdownMenuCheckboxItem,
DropdownMenuContent,
DropdownMenuItem,
DropdownMenuItemIndicator,
DropdownMenuPortal,
DropdownMenuRoot,
DropdownMenuSeparator,
DropdownMenuTrigger,
} from 'akar'
import { ref } from 'vue'
const checked = ref(false)
</script>
<template>
<DropdownMenuRoot>
<DropdownMenuTrigger>…</DropdownMenuTrigger>
<DropdownMenuPortal>
<DropdownMenuContent>
<DropdownMenuItem>…</DropdownMenuItem>
<DropdownMenuItem>…</DropdownMenuItem>
<DropdownMenuSeparator />
<DropdownMenuCheckboxItem v-model="checked">
<DropdownMenuItemIndicator>
<Icon icon="radix-icons:check" />
</DropdownMenuItemIndicator>
Checkbox item
</DropdownMenuCheckboxItem>
</DropdownMenuContent>
</DropdownMenuPortal>
</DropdownMenuRoot>
</template>
With radio items
Use the RadioGroup and RadioItem parts to add an item that can be checked amongst others.
<script setup lang="ts">
import { Icon } from '@iconify/vue'
import {
DropdownMenuContent,
DropdownMenuItemIndicator,
DropdownMenuPortal,
DropdownMenuRadioGroup,
DropdownMenuRadioItem,
DropdownMenuRoot,
DropdownMenuTrigger,
} from 'akar'
import { ref } from 'vue'
const color = ref(false)
</script>
<template>
<DropdownMenuRoot>
<DropdownMenuTrigger>…</DropdownMenuTrigger>
<DropdownMenuPortal>
<DropdownMenuContent>
<DropdownMenuRadioGroup v-model="color">
<DropdownMenuRadioItem value="red">
<DropdownMenuItemIndicator>
<Icon icon="radix-icons:check" />
</DropdownMenuItemIndicator>
Red
</DropdownMenuRadioItem>
<DropdownMenuRadioItem value="blue">
<DropdownMenuItemIndicator>
<Icon icon="radix-icons:check" />
</DropdownMenuItemIndicator>
Blue
</DropdownMenuRadioItem>
<DropdownMenuRadioItem value="green">
<DropdownMenuItemIndicator>
<Icon icon="radix-icons:check" />
</DropdownMenuItemIndicator>
Green
</DropdownMenuRadioItem>
</DropdownMenuRadioGroup>
</DropdownMenuContent>
</DropdownMenuPortal>
</DropdownMenuRoot>
</template>
With complex items
You can add extra decorative elements in the Item parts, such as images.
<script setup lang="ts">
import {
DropdownMenuContent,
DropdownMenuItem,
DropdownMenuPortal,
DropdownMenuRoot,
DropdownMenuTrigger,
} from 'akar'
</script>
<template>
<DropdownMenuRoot>
<DropdownMenuTrigger>…</DropdownMenuTrigger>
<DropdownMenuPortal>
<DropdownMenuContent>
<DropdownMenuItem>
<img src="…">
Adolfo Hess
</DropdownMenuItem>
<DropdownMenuItem>
<img src="…">
Miyah Myles
</DropdownMenuItem>
</DropdownMenuContent>
</DropdownMenuPortal>
</DropdownMenuRoot>
</template>
Constrain the content/sub-content size
You may want to constrain the width of the content (or sub-content) so that it matches the trigger (or sub-trigger) width. You may also want to constrain its height to not exceed the viewport.
We expose several CSS custom properties such as --akar-dropdown-menu-trigger-width and --akar-dropdown-menu-content-available-height to support this. Use them to constrain the content dimensions.
<script setup lang="ts">
import { DropdownMenuContent, DropdownMenuPortal, DropdownMenuRoot, DropdownMenuTrigger } from 'akar'
</script>
<template>
<DropdownMenuRoot>
<DropdownMenuTrigger>…</DropdownMenuTrigger>
<DropdownMenuPortal>
<DropdownMenuContent
class="DropdownMenuContent"
:side-offset="5"
>
…
</DropdownMenuContent>
</DropdownMenuPortal>
</DropdownMenuRoot>
</template>
/* styles.css */
.DropdownMenuContent {
width: var(--akar-dropdown-menu-trigger-width);
max-height: var(--akar-dropdown-menu-content-available-height);
}
Origin-aware animations
We expose a CSS custom property --akar-dropdown-menu-content-transform-origin. Use it to animate the content from its computed origin based on side, sideOffset, align, alignOffset and any collisions.
<script setup lang="ts">
import { DropdownMenuContent, DropdownMenuPortal, DropdownMenuRoot, DropdownMenuTrigger } from 'akar'
</script>
<template>
<DropdownMenuRoot>
<DropdownMenuTrigger>…</DropdownMenuTrigger>
<DropdownMenuPortal>
<DropdownMenuContent class="DropdownMenuContent">
…
</DropdownMenuContent>
</DropdownMenuPortal>
</DropdownMenuRoot>
</template>
/* styles.css */
.DropdownMenuContent {
transform-origin: var(--akar-dropdown-menu-content-transform-origin);
animation: scaleIn 0.5s ease-out;
}
@keyframes scaleIn {
from {
opacity: 0;
transform: scale(0);
}
to {
opacity: 1;
transform: scale(1);
}
}
Collision-aware animations
We expose data-side and data-align attributes. Their values will change at runtime to reflect collisions. Use them to create collision and direction-aware animations.
<script setup lang="ts">
import { DropdownMenuContent, DropdownMenuPortal, DropdownMenuRoot, DropdownMenuTrigger } from 'akar'
</script>
<template>
<DropdownMenuRoot>
<DropdownMenuTrigger>…</DropdownMenuTrigger>
<DropdownMenuPortal>
<DropdownMenuContent class="DropdownMenuContent">
…
</DropdownMenuContent>
</DropdownMenuPortal>
</DropdownMenuRoot>
</template>
/* styles.css */
.DropdownMenuContent {
animation-duration: 0.6s;
animation-timing-function: cubic-bezier(0.16, 1, 0.3, 1);
}
.DropdownMenuContent[data-side="top"] {
animation-name: slideUp;
}
.DropdownMenuContent[data-side="bottom"] {
animation-name: slideDown;
}
@keyframes slideUp {
from {
opacity: 0;
transform: translateY(10px);
}
to {
opacity: 1;
transform: translateY(0);
}
}
@keyframes slideDown {
from {
opacity: 0;
transform: translateY(-10px);
}
to {
opacity: 1;
transform: translateY(0);
}
}
With filtering
Use DropdownMenuFilter with a computed list to control which items are displayed. This example matches labels without regard to case and displays a message when no items match.
<script setup lang="ts">
import {
DropdownMenuContent,
DropdownMenuFilter,
DropdownMenuItem,
DropdownMenuPortal,
DropdownMenuRoot,
DropdownMenuTrigger,
useId,
} from 'akar';
import { computed, ref } from 'vue';
const menuId = useId();
const search = ref('');
const items = [
{ id: 'new-tab', label: 'New Tab' },
{ id: 'new-window', label: 'New Window' },
{ id: 'bookmarks', label: 'Show Bookmarks' },
{ id: 'history', label: 'Show History' },
];
const filteredItems = computed(() =>
items.filter((item) =>
item.label.toLowerCase().includes(search.value.toLowerCase()),
),
);
</script>
<template>
<DropdownMenuRoot>
<DropdownMenuTrigger>Browse actions</DropdownMenuTrigger>
<DropdownMenuPortal>
<DropdownMenuContent>
<DropdownMenuFilter
v-model="search"
auto-focus
aria-label="Filter actions"
placeholder="Filter actions…"
/>
<DropdownMenuItem
v-for="item in filteredItems"
:id="`${menuId}-${item.id}`"
:key="item.id"
>
{{ item.label }}
</DropdownMenuItem>
<div v-if="filteredItems.length === 0">
No actions found.
</div>
</DropdownMenuContent>
</DropdownMenuPortal>
</DropdownMenuRoot>
</template>
Accessibility
Adheres to the Menu Button WAI-ARIA design pattern and uses roving tabindex to manage focus movement among menu items.
Keyboard Interactions
| Key | Description |
|---|
When focus is on an item, activates the focused item.
`,
},
{
keys: ['Enter'],
description: `
When focus is on <Code>DropdownMenuTrigger</Code>, opens the dropdown
menu and focuses the first item.
<br />
When focus is on an item, activates the focused item.
`,
},
{
keys: ['ArrowDown'],
description: `
When focus is on <Code>DropdownMenuTrigger</Code>, opens the dropdown
menu.
<br />
When focus is on an item, moves focus to the next item.
`,
},
{
keys: ['ArrowUp'],
description: `
When focus is on an item, moves focus to the previous item.
`,
},
{
keys: ['ArrowRight', 'ArrowLeft'],
description: `
When focus is on <Code>DropdownMenuSubTrigger</Code>, opens or closes
the submenu depending on reading direction.
`,
},
{
keys: ['Esc'],
description: `
Closes the dropdown menu and moves focus to{' '}
<Code>DropdownMenuTrigger</Code>.
`,
},
]" />
When focus is on the filter
The input keeps focus while keyboard navigation updates the highlighted item through aria-activedescendant.
| Key | Description |
|---|---|
| ArrowDown/ArrowUp | Highlights the next or previous enabled item. |
| Home/End | Highlights the first or last enabled item. |
| Enter | Activates the highlighted item. |
| Esc | Clears a non-empty filter without closing the menu. If the filter is empty, closes the menu and returns focus to the trigger. |
Custom APIs
Create your own API by abstracting the primitive parts into your own component.
Abstract the arrow and item indicators
This example abstracts the DropdownMenuArrow and DropdownMenuItemIndicator parts. It also wraps implementation details for CheckboxItem and RadioItem.
Usage
<script setup lang="ts">
import {
DropdownMenu,
DropdownMenuCheckboxItem,
DropdownMenuContent,
DropdownMenuGroup,
DropdownMenuItem,
DropdownMenuLabel,
DropdownMenuRadioGroup,
DropdownMenuRadioItem,
DropdownMenuSeparator,
DropdownMenuTrigger,
} from './your-dropdown-menu';
</script>
<template>
<DropdownMenu>
<DropdownMenuTrigger>DropdownMenu trigger</DropdownMenuTrigger>
<DropdownMenuContent>
<DropdownMenuItem>Item</DropdownMenuItem>
<DropdownMenuLabel>Label</DropdownMenuLabel>
<DropdownMenuGroup>Group</DropdownMenuGroup>
<DropdownMenuCheckboxItem>CheckboxItem</DropdownMenuCheckboxItem>
<DropdownMenuSeparator>Separator</DropdownMenuSeparator>
<DropdownMenuRadioGroup>
<DropdownMenuRadioItem>RadioItem</DropdownMenuRadioItem>
<DropdownMenuRadioItem>RadioItem</DropdownMenuRadioItem>
</DropdownMenuRadioGroup>
</DropdownMenuContent>
</DropdownMenu>
</template>
Implementation
export {
DropdownMenuRoot as DropdownMenu,
DropdownMenuGroup,
DropdownMenuItem,
DropdownMenuLabel,
DropdownMenuRadioGroup,
DropdownMenuSeparator,
DropdownMenuTrigger
} from 'akar';
export { default as DropdownMenuCheckboxItem } from 'DropdownMenuCheckboxItem.vue';
// your-dropdown-menu.ts
export { default as DropdownMenuContent } from 'DropdownMenuContent.vue';
export { default as DropdownMenuRadioItem } from 'DropdownMenuRadioItem.vue';
<!-- DropdownMenuContent.vue -->
<script setup lang="ts">
import type { DropdownMenuContentEmits, DropdownMenuContentProps } from 'akar';
import { DropdownMenuContent, DropdownMenuPortal, useForwardPropsEmits } from 'akar';
const props = defineProps<DropdownMenuContentProps>();
const emits = defineEmits<DropdownMenuContentEmits>();
const forwarded = useForwardPropsEmits(props, emits);
</script>
<template>
<DropdownMenuPortal>
<DropdownMenuContent v-bind="forwarded">
<slot />
</DropdownMenuContent>
</DropdownMenuPortal>
</template>
<!-- DropdownMenuCheckboxItem.vue -->
<script setup lang="ts">
import type { DropdownMenuCheckboxItemEmits, DropdownMenuCheckboxItemProps } from 'akar';
import { CheckIcon } from '@radix-icons/vue';
import { DropdownMenuCheckboxItem, DropdownMenuItemIndicator, useForwardPropsEmits } from 'akar';
const props = defineProps<DropdownMenuCheckboxItemProps>();
const emits = defineEmits<DropdownMenuCheckboxItemEmits>();
const forwarded = useForwardPropsEmits(props, emits);
</script>
<template>
<DropdownMenuCheckboxItem v-bind="forwarded">
<DropdownMenuItemIndicator>
<CheckIcon />
</DropdownMenuItemIndicator>
<slot />
</DropdownMenuCheckboxItem>
</template>
<!-- DropdownMenuRadioItem.vue -->
<script setup lang="ts">
import type { DropdownMenuRadioItemEmits, DropdownMenuRadioItemProps } from 'akar';
import { DotFilledIcon } from '@radix-icons/vue';
import { DropdownMenuItemIndicator, DropdownMenuRadioItem, useForwardPropsEmits } from 'akar';
const props = defineProps<DropdownMenuRadioItemProps>();
const emits = defineEmits<DropdownMenuRadioItemEmits>();
const forwarded = useForwardPropsEmits(props, emits);
</script>
<template>
<DropdownMenuRadioItem v-bind="forwarded">
<DropdownMenuItemIndicator>
<DotFilledIcon />
</DropdownMenuItemIndicator>
<slot />
</DropdownMenuRadioItem>
</template>