Dialog (Modal)

A fully-managed, renderless dialog component jam-packed with accessibility and keyboard features, perfect for building completely custom modal and dialog windows for your next application.

Payment successful

Your payment has been successfully submitted. We’ve sent you an email with all of the details of your order.

Installation

To get started, install Headless UI via npm:

npm install @headlessui/react

Basic example

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>
  )
}

Styling the active item

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

To style the active `Menu.Item` you can read the `active` render 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.

import { Menu } from '@headlessui/react'

function MyDropdown() {
  return (
    <Menu>
      <Menu.Button>More</Menu.Button>
      <Menu.Items>
        {/* Use the `active` render prop to conditionally style the active item. */}
        <Menu.Item>
          {({ active }) => (
            <a
              className={`${
                active ? 'bg-blue-500 text-white' : 'bg-white text-black'
              }`}
              href="/account-settings"
            >
              Account settings
            </a>
          )}
        </Menu.Item>
        {/* ... */}
      </Menu.Items>
    </Menu>
  )
}

Showing/hiding the 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, this 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 `static`, `Menu.Items` is always rendered and
                ignores the `open` state.
              */}
              <Menu.Items static>
                <Menu.Item>{/* ... */}</Menu.Item>
                {/* ... */}
              </Menu.Items>
            </div>
          )}
        </>
      )}
    </Menu>
  )
}

Disabling an item

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>
  )
}

Transitions

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>
  )
}

Accessibility notes

Focus management

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` .

Mouse interaction

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

Keyboard interaction

Command	Description
`EnterSpace` when `Menu.Button` is focused	Opens menu and focuses first non-disabled item
when `Menu.Button` is focused	Opens menu and focuses first/last non-disabled item
`Esc` when menu is open	Closes any open Menus
when menu is open	Focuses previous/next non-disabled item
`HomeEnd` when menu is open	Focuses first/last non-disabled item
`EnterSpace` when menu is open	Activates/clicks the current menu item
`A-Za-z` when menu is open	Focuses first item that matches keyboard input

Other

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.

When to use a Menu

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 navigatethrough 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 theapplication's contents. They also capture focus and prevent tabbing away from theDialog's contents until the Dialog is dismissed

Component API

Styled examples

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.

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

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.