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:

npm install @headlessui/react

Menu Buttons are built using the Menu, Menu.Button, Menu.Items, and Menu.Item components.

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

import { Menu } from '@headlessui/react'

function MyDropdown() {
  return (
    <Menu>
      <Menu.Button>More</Menu.Button>
      <Menu.Items>
        <Menu.Item>
          {({ active }) => (
            <a
              className={`${active && 'bg-blue-500'}`}
              href="/account-settings"
            >
              Account settings
            </a>
          )}
        </Menu.Item>
        <Menu.Item>
          {({ active }) => (
            <a
              className={`${active && 'bg-blue-500'}`}
              href="/account-settings"
            >
              Documentation
            </a>
          )}
        </Menu.Item>
        <Menu.Item disabled>
          <span className="opacity-75">Invite a friend (coming soon!)</span>
        </Menu.Item>
      </Menu.Items>
    </Menu>
  )
}

Headless UI keeps track of a lot of state about each component, like which listbox option is currently selected, whether a popover is open or closed, or which item in a menu is currently active via the keyboard.

But because the components are headless and completely unstyled out of the box, you can't see this information in your UI until you provide the styles you want for each state yourself.

Each component exposes information about its current state via render props that you can use to conditionally apply different styles or render different content.

For example, the Menu.Item component exposes an active state, which tells you if the item is currently focused via the mouse or keyboard.

import { Fragment } from 'react'
import { Menu } from '@headlessui/react'

const links = [
  { href: '/account-settings', label: 'Account settings' },
  { href: '/support', label: 'Support' },
  { href: '/license', label: 'License' },
  { href: '/sign-out', label: 'Sign out' },
]

function MyMenu() {
  return (
    <Menu>
      <Menu.Button>Options</Menu.Button>
      <Menu.Items>
        {links.map((link) => (
          /* Use the `active` state to conditionally style the active item. */
          <Menu.Item key={link.href} as={Fragment}>
            {({ active }) => (
              <a
                href={link.href}
                className={`${
                  active ? 'bg-blue-500 text-white' : 'bg-white text-black'
                }`}
              >
                {link.label}
              </a>
            )}
          </Menu.Item>
        ))}
      </Menu.Items>
    </Menu>
  )
}

For the complete render prop API for each component, see the component API documentation.

Each component also exposes information about its current state via a data-headlessui-state attribute that you can use to conditionally apply different styles.

When any of the states in the render prop API are true, they will be listed in this attribute as space-separated strings so you can target them with a CSS attribute selector in the form [attr~=value].

For example, here's what the Menu.Items component with some child Menu.Item components renders when the menu is open and the second item is active:

<!-- Rendered `Menu.Items` -->
<ul data-headlessui-state="open">
  <li data-headlessui-state="">Account settings</li>
  <li data-headlessui-state="active">Support</li>
  <li data-headlessui-state="">License</li>
</ul>

If you are using Tailwind CSS, you can use the @headlessui/tailwindcss plugin to target this attribute with modifiers like ui-open:* and ui-active:*:

import { Menu } from '@headlessui/react'

const links = [
  { href: '/account-settings', label: 'Account settings' },
  { href: '/support', label: 'Support' },
  { href: '/license', label: 'License' },
  { href: '/sign-out', label: 'Sign out' },
]

function MyMenu() {
  return (
    <Menu>
      <Menu.Button>Options</Menu.Button>
      <Menu.Items>
        {links.map((link) => (
          <Menu.Item
            as="a"
            key={link.href}
            href={link.href}
            className="ui-active:bg-blue-500 ui-active:text-white ui-not-active:bg-white ui-not-active:text-black"
          >
            {link.label}
          </Menu.Item>
        ))}
      </Menu.Items>
    </Menu>
  )
}

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

import { Menu } from '@headlessui/react'

function MyDropdown() {
  return (
    <Menu>
      <Menu.Button>More</Menu.Button>

      {/*
        By default, the `Menu.Items` will automatically show/hide
        when the `Menu.Button` is pressed.
      */}
      <Menu.Items>
        <Menu.Item>{/* ... */}</Menu.Item>
        {/* ... */}
      </Menu.Items>
    </Menu>
  )
}

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 Menu.Items 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.

import { Menu } from '@headlessui/react'

function MyDropdown() {
  return (
    <Menu>
      {({ open }) => (
        <>
          <Menu.Button>More</Menu.Button>
          {open && (
            <div>
              {/*
                Using the `static` prop, the `Menu.Items` are always
                rendered and the `open` state is ignored.
              */}
              <Menu.Items static>
                <Menu.Item>{/* ... */}</Menu.Item>
                {/* ... */}
              </Menu.Items>
            </div>
          )}
        </>
      )}
    </Menu>
  )
}

The menu will already close by default, however it can happen that 3rd party Link components use event.preventDefault(), which prevents the default behaviour and therefore won't close the menu.

The Menu and Menu.Item expose a close() render prop which you can use to imperatively close the menu:

import { Menu } from '@headlessui/react'
import { MyCustomLink } from './MyCustomLink'

function MyMenu() {
  return (
    <Menu>
      <Menu.Button>Terms</Menu.Button>

      <Menu.Items>
        <Menu.Item>
          {({ close }) => (
            <MyCustomLink href="/" onClick={close}>
              Read and accept
            </MyCustomLink>
          )}
        </Menu.Item>
      </Menu.Items>
    </Menu>
  )
}

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

import { Menu } from '@headlessui/react'

function MyDropdown() {
  return (
    <Menu>
      <Menu.Button>More</Menu.Button>
      <Menu.Items>
        {/* ... */}

        {/* This item will be skipped by keyboard navigation. */}
        <Menu.Item disabled>
          <span className="opacity-75">Invite a friend (coming soon!)</span>
        </Menu.Item>

        {/* ... */}
      </Menu.Items>
    </Menu>
  )
}

To animate the opening/closing of the menu panel, use the provided Transition component. All you need to do is wrap the Menu.Items in a <Transition>, and the transition will be applied automatically.

import { Menu, Transition } from '@headlessui/react'

function MyDropdown() {
  return (
    <Menu>
      <Menu.Button>More</Menu.Button>

      {/* Use the `Transition` component. */}
      <Transition
        enter="transition duration-100 ease-out"
        enterFrom="transform scale-95 opacity-0"
        enterTo="transform scale-100 opacity-100"
        leave="transition duration-75 ease-out"
        leaveFrom="transform scale-100 opacity-100"
        leaveTo="transform scale-95 opacity-0"
      >
        <Menu.Items>
          <Menu.Item>{/* ... */}</Menu.Item>
          {/* ... */}
        </Menu.Items>
      </Transition>
    </Menu>
  )
}

By default our built-in Transition component automatically communicates with the Menu components to handle the open/closed states. However, if you require more control over this behavior, you can explicitly control it:

import { Menu, Transition } from '@headlessui/react'

function MyDropdown() {
  return (
    <Menu>
      {({ open }) => (
        <>
          <Menu.Button>More</Menu.Button>

          {/* Use the `Transition` component. */}
          <Transition
            show={open}
            enter="transition duration-100 ease-out"
            enterFrom="transform scale-95 opacity-0"
            enterTo="transform scale-100 opacity-100"
            leave="transition duration-75 ease-out"
            leaveFrom="transform scale-100 opacity-100"
            leaveTo="transform scale-95 opacity-0"
          >
            {/* Mark this component as `static` */}
            <Menu.Items static>
              <Menu.Item>{/* ... */}</Menu.Item>
              {/* ... */}
            </Menu.Items>
          </Transition>
        </>
      )}
    </Menu>
  )
}

Because they're renderless, Headless UI components also compose well with other animation libraries in the React ecosystem like Framer Motion and React Spring.

The accessibility semantics of role="menu" are fairly strict and any children of a Menu that are not Menu.Item 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 Menu.Item 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, Menu.Button renders a button by default, and Menu.Items renders a div. By contrast, Menu and Menu.Item do not render an element, and instead render their children directly by default.

Use the as prop to render a component as a different element or as your own custom component, making sure your custom components forward refs so that Headless UI can wire things up correctly.

import { forwardRef } from 'react'
import { Menu } from '@headlessui/react'
let MyCustomButton = forwardRef(function (props, ref) {
  return <button className="..." ref={ref} {...props} />
})

function MyDropdown() {
  return (
    <Menu>
      <Menu.Button as={MyCustomButton}>More</Menu.Button>
      <Menu.Items as="section">
        <Menu.Item>
          {({ active }) => (
            <a
              className={`${active && 'bg-blue-500'}`}
              href="/account-settings"
            >
              Account settings
            </a>
          )}
        </Menu.Item>

        {/* ... */}
      </Menu.Items>
    </Menu>
  )
}

To tell an element to render its children directly with no wrapper element, use as={React.Fragment}.

import { Menu } from '@headlessui/react'

function MyDropdown() {
  return (
    <Menu>
      {/* Render no wrapper, instead pass in a `button` manually. */}
      <Menu.Button as={React.Fragment}>
        <button>More</button>
      </Menu.Button>
      <Menu.Items>
        <Menu.Item>
          {({ active }) => (
            <a
              className={`${active && 'bg-blue-500'}`}
              href="/account-settings"
            >
              Account settings
            </a>
          )}
        </Menu.Item>
        {/* ... */}
      </Menu.Items>
    </Menu>
  )
}

This is important if you are using an interactive element like an <a> tag inside the Menu.Item. If the Menu.Item had an as="div", then the props provided by Headless UI would be forwarded to the div instead of the a, which means that you can't go to the URL provided by the <a> tag anymore via your keyboard.

Prior to Next.js v13, the Link component did not forward unknown props to the underlying a element, preventing the menu from closing on click when used inside a Menu.Item.

If you're using Next.js v12 or older, you can work around this issue by creating your own component that wraps Link and forwards unknown props to the child a element:


import { forwardRef } from 'react'
import Link from 'next/link'
import { Menu } from '@headlessui/react'

const MyLink = forwardRef((props, ref) => {
  let { href, children, ...rest } = props
  return (
    <Link href={href}>
      <a ref={ref} {...rest}>
        {children}
      </a>
    </Link>
  )
})
function Example() {
  return (
    <Menu>
      <Menu.Button>More</Menu.Button>
      <Menu.Items>
        <Menu.Item>
          <MyLink href="/profile">Profile</MyLink>
        </Menu.Item>
      </Menu.Items>
    </Menu>
  )
}

This will ensure that all of the event listeners Headless UI needs to add to the a element are properly applied.

This behavior was changed in Next.js v13 making this workaround no longer necessary.

Clicking the Menu.Button toggles the menu and focuses the Menu.Items 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 Menu.Button.

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

Command	Description
`Enter` or `Space` when `Menu.Button` is focused	Opens menu and focuses first non-disabled item
`ArrowDown` or `ArrowUp` when `Menu.Button` 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 `PageUp` when menu is open	Focuses first non-disabled item
`End` or `PageDown` when menu is open	Focuses 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.

Prop	Default	Description
`as`	`Fragment`	`String \| Component` The element or component the `Menu` should render as.

Render Prop	Description
`open`	`Boolean` Whether or not the Menu is open.
`close`	`() => void` Closes the menu and refocuses `Menu.Button`.

Prop	Default	Description
`as`	`button`	`String \| Component` The element or component the `Menu.Button` should render as.

Render Prop	Description
`open`	`Boolean` Whether or not the Menu is open.

Prop	Default	Description
`as`	`div`	`String \| Component` The element or component the `Menu.Items` should render as.
`static`	`false`	`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.
`unmount`	`true`	`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.

Render Prop	Description
`open`	`Boolean` Whether or not the Menu is open.

Prop	Default	Description
`as`	`Fragment`	`String \| Component` The element or component the `Menu.Item` should render as.
`disabled`	`false`	`Boolean` Whether or not the item should be disabled for keyboard navigation and ARIA purposes.

Render Prop	Description
`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.
`close`	`() => void` Closes the menu and refocuses `Menu.Button`.

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.