Menu (Dropdown)

Menus offer an easy way to build custom, accessible dropdown components with robust support for keyboard navigation.

To get started, install Headless UI via npm or yarn.

Please note that this library only supports Vue 3.

# npm npm install @headlessui/vue # Yarn yarn add @headlessui/vue

Menu Buttons are built using the Menu, MenuButton, MenuItems, and MenuItem components.

The MenuButton will automatically open/close the MenuItems when clicked, and when the menu is open, the list of items receives focus and is automatically navigable via the keyboard.

<template> <Menu> <MenuButton>More</MenuButton> <MenuItems> <MenuItem v-slot="{ active }"> <a :class='{ "bg-blue-500": active }' href="/account-settings"> Account settings </a> </MenuItem> <MenuItem v-slot="{ active }"> <a :class='{ "bg-blue-500": active }' href="/account-settings"> Documentation </a> </MenuItem> <MenuItem disabled> <span class="opacity-75">Invite a friend (coming soon!)</span> </MenuItem> </MenuItems> </Menu> </template> <script> import { Menu, MenuButton, MenuItems, MenuItem } from "@headlessui/vue"; export default { components: { Menu, MenuButton, MenuItems, MenuItem, }, }; </script>

This is a headless component so there are no styles included by default. Instead, the components expose useful information via scoped slots that you can use to apply the styles you'd like to apply yourself.

To style the active MenuItem you can read the active slot prop argument, which tells you whether or not that menu item is currently focused via the mouse or keyboard.

You can use this state to conditionally apply whatever active/focus styles you like, for instance a blue background like is typical in most operating systems.

<template> <Menu> <MenuButton>More</MenuButton> <MenuItems> <!-- Use the `active` slot prop to conditionally style the active item. -->
<MenuItem v-slot="{ active }">
<a
:class="[
active
? 'bg-blue-500 text-white'
: 'bg-white text-black',
]"
href="/account-settings" >
Account settings </a> </MenuItem> <!-- ... --> </MenuItems> </Menu> </template> <script> import { Menu, MenuButton, MenuItems, MenuItem } from "@headlessui/vue"; export default { components: { Menu, MenuButton, MenuItems, MenuItem, }, }; </script>

By default, your MenuItems instance will be shown/hidden automatically based on the internal open state tracked within the Menu component itself.

<template> <Menu> <MenuButton>More</MenuButton> <!-- By default, this will automatically show/hide when the MenuButton is pressed. --> <MenuItems> <MenuItem><!-- ... --></MenuItem> <!-- ... --> </MenuItems> </Menu> </template> <script> import { Menu, MenuButton, MenuItems, MenuItem } from "@headlessui/vue"; export default { components: { Menu, MenuButton, MenuItems, MenuItem, }, }; </script>

If you'd rather handle this yourself (perhaps because you need to add an extra wrapper element for one reason or another), you can add a static prop to the MenuItems instance to tell it to always render, and inspect the open slot prop provided by the Menu to control which element is shown/hidden yourself.

<template>
<Menu v-slot="{ open }">
<MenuButton>More</MenuButton>
<div v-show="open">
<!-- Using `static`, `MenuItems` is always rendered and ignores the `open` state. -->
<MenuItems static>
<MenuItem><!-- ... --></MenuItem> <!-- ... --> </MenuItems> </div> </Menu> </template> <script> import { Menu, MenuButton, MenuItems, MenuItem } from "@headlessui/vue"; export default { components: { Menu, MenuButton, MenuItems, MenuItem, }, }; </script>

Use the disabled prop to disable a MenuItem. This will make it unselectable via keyboard navigation, and it will be skipped when pressing the up/down arrows.

<template> <Menu> <MenuButton>More</MenuButton> <MenuItems> <!-- ... --> <!-- This item will be skipped by keyboard navigation. -->
<MenuItem disabled>
<span class="opacity-75">Invite a friend (coming soon!)</span> </MenuItem> </MenuItems> </Menu> </template> <script> import { Menu, MenuButton, MenuItems, MenuItem } from "@headlessui/vue"; export default { components: { Menu, MenuButton, MenuItems, MenuItem, }, }; </script>

To animate the opening/closing of the menu panel, you can use Vue's built-in <transition> component. All you need to do is wrap your MenuItems instance in a <transition>, and the transition will be applied automatically.

<template> <Menu> <MenuButton>More</MenuButton> <!-- Use Vue's built-in <transition> element to add transitions. -->
<transition
enter-active-class="transition duration-100 ease-out"
enter-from-class="transform scale-95 opacity-0"
enter-to-class="transform scale-100 opacity-100"
leave-active-class="transition duration-75 ease-out"
leave-from-class="transform scale-100 opacity-100"
leave-to-class="transform scale-95 opacity-0"
>
<MenuItems> <MenuItem><!-- ... --></MenuItem> <!-- ... --> </MenuItems> </transition> </Menu> </template> <script> import { Menu, MenuButton, MenuItems, MenuItem } from "@headlessui/vue"; export default { components: { Menu, MenuButton, MenuItems, MenuItem, }, }; </script>

If you'd like to coordinate multiple transitions for different children of your Menu, check out the Transition component included in Headless UI.

The accessibility semantics of role="menu" are fairly strict and any children of a Menu that are not MenuItem components will be automatically hidden from assistive technology to make sure the menu works the way screen reader users expect.

For this reason, rendering any children other than MenuItem components is discouraged as that content will be inaccessible to people using assistive technology.

If you want to build a dropdown with more flexible content, consider using Popover instead.

By default, the Menu and its subcomponents each render a default element that is sensible for that component.

For example, MenuButton renders a button by default, and MenuItems renders a div. Menu and MenuItem interestingly do not render an extra element, and instead render their children directly by default.

This is easy to change using the as prop, which exists on every component.

<template> <!-- Render a `div` instead of no wrapper element -->
<Menu as="div">
<MenuButton>More</MenuButton> <!-- Render a `ul` instead of a `div` -->
<MenuItems as="ul">
<!-- Render an `li` instead of no wrapper element -->
<MenuItem as="li" v-slot="{ active }">
<a :class='{ "bg-blue-500": active }' href="/account-settings"> Account settings </a> </MenuItem> <!-- ... --> </MenuItems> </Menu> </template> <script> import { Menu, MenuButton, MenuItems, MenuItem } from "@headlessui/vue"; export default { components: { Menu, MenuButton, MenuItems, MenuItem, }, }; </script>

To tell an element to render its children directly with no wrapper element, use as="template".

<template> <Menu> <!-- Render no wrapper, instead pass in a button manually. -->
<MenuButton as="template">
<button>More</button> </MenuButton> <MenuItems> <MenuItem v-slot="{ active }"> <a :class='{ "bg-blue-500": active }' href="/account-settings"> Account settings </a> </MenuItem> <!-- ... --> </MenuItems> </Menu> </template> <script> import { Menu, MenuButton, MenuItems, MenuItem } from "@headlessui/vue"; export default { components: { Menu, MenuButton, MenuItems, MenuItem, }, }; </script>

Clicking the MenuButton toggles the menu and focuses the MenuItems component. Focus is trapped within the open menu until Escape is pressed or the user clicks outside the menu. Closing the menu returns focus to the MenuButton.

Clicking a MenuButton toggles the menu. Clicking anywhere outside of an open menu will close that menu.

CommandDescription

Enter or Space when MenuButton is focused

Opens menu and focuses first non-disabled item

ArrowDown or ArrowUp when MenuButton is focused

Opens menu and focuses first/last non-disabled item

Esc when menu is open

Closes any open Menus

ArrowDown or ArrowUp when menu is open

Focuses previous/next non-disabled item

Home or End when menu is open

Focuses first/last non-disabled item

Enter or Space when menu is open

Activates/clicks the current menu item

A–Z or a–z when menu is open

Focuses first item that matches keyboard input

All relevant ARIA attributes are automatically managed.

For a full reference on all accessibility features implemented in Menu, see the ARIA spec on Menu Buttons.

Menus are best for UI elements that resemble things like the menus you'd find in the title bar of most operating systems. They have specific accessibility semantics, and their content should be restricted to a list of links or buttons. Focus is trapped in an open menu, so you cannot Tab through the content or away from the menu. Instead, the arrow keys navigate through a Menu's items.

Here's when you might use other similar components from Headless UI:

  • <Popover />. Popovers are general-purpose floating menus. They appear near the button that triggers them, and you can put arbitrary markup in them like images or non-clickable content. The Tab key navigates the contents of a Popover like it would any other normal markup. They're great for building header nav items with expandable content and flyout panels.

  • <Disclosure />. Disclosures are useful for elements that expand to reveal additional information, like a toggleable FAQ section. They are typically rendered inline and reflow the document when they're shown or hidden.

  • <Dialog />. Dialogs are meant to grab the user's full attention. They typically render a floating panel in the center of the screen, and use a backdrop to dim the rest of the application's contents. They also capture focus and prevent tabbing away from the Dialog's contents until the Dialog is dismissed.

PropDefaultDescription
astemplate
String | Component

The element or component the Menu should render as.

Slot PropDescription
open

Boolean

Whether or not the Menu is open.

PropDefaultDescription
asbutton
String | Component

The element or component the MenuButton should render as.

Slot PropDescription
open

Boolean

Whether or not the Menu is open.

PropDefaultDescription
asdiv
String | Component

The element or component the MenuItems should render as.

staticfalse
Boolean

Whether the element should ignore the internally managed open/closed state.

Note: static and unmount can not be used at the same time. You will get a TypeScript error if you try to do it.

unmounttrue
Boolean

Whether the element should be unmounted or hidden based on the open/closed state.

Note: static and unmount can not be used at the same time. You will get a TypeScript error if you try to do it.

Slot PropDescription
open

Boolean

Whether or not the Menu is open.

PropDefaultDescription
astemplate
String | Component

The element or component the MenuItem should render as.

disabledfalse
Boolean

Whether or not the item should be disabled for keyboard navigation and ARIA purposes.

Slot PropDescription
active

Boolean

Whether or not the item is the active/focused item in the list.

disabled

Boolean

Whether or not the item is the disabled for keyboard navigation and ARIA purposes.

If you're interested in predesigned component examples using Headless UI and Tailwind CSS, check out Tailwind UI — a collection of beautifully designed and expertly crafted components built by us.

It's a great way to support our work on open-source projects like this and makes it possible for us to improve them and keep them well-maintained.