Popover

Installation

To get started, install Headless UI via npm:

npm install @headlessui/react

Basic example

Popovers are built using the Popover, Popover.Button, and Popover.Panel components.

Clicking the Popover.Button will automatically open/close the Popover.Panel. When the panel is open, clicking anywhere outside of its contents, pressing the Escape key, or tabbing away from it will close the Popover.

import { Popover } from '@headlessui/react'

function MyPopover() {
  return (
    <Popover className="relative">
      <Popover.Button>Solutions</Popover.Button>

      <Popover.Panel className="absolute z-10">
        <div className="grid grid-cols-2">
          <a href="/analytics">Analytics</a>
          <a href="/engagement">Engagement</a>
          <a href="/security">Security</a>
          <a href="/integrations">Integrations</a>
        </div>

        <img src="/solutions.jpg" alt="" />
      </Popover.Panel>
    </Popover>
  )
}

These components are completely unstyled, so how you style your Popover is up to you. In our example we're using absolute positioning on the Popover.Panel to position it near the Popover.Button and not disturb the normal document flow.

Styling different states

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

Using render props

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 Popover component exposes an open state, which tells you if the popover is currently open.

import { Popover } from '@headlessui/react'
import { ChevronDownIcon } from '@heroicons/react/20/solid'

function MyPopover() {
  return (
    <Popover>
      {({ open }) => (
        /* Use the `open` state to conditionally change the direction of the chevron icon. */
        <>
          <Popover.Button>
            Solutions
            <ChevronDownIcon className={open ? 'rotate-180 transform' : ''} />
          </Popover.Button>
          <Popover.Panel>
            <a href="/insights">Insights</a>
            <a href="/automations">Automations</a>
            <a href="/reports">Reports</a>
          </Popover.Panel>
        </>
      )}
    </Popover>
  )
}

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

Using data attributes

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 Popover component renders when the popover is open:

<!-- Rendered `Popover` -->
<div data-headlessui-state="open">
  <button data-headlessui-state="open">Solutions</button>
  <div data-headlessui-state="open">
    <a href="/insights">Insights</a>
    <a href="/automations">Automations</a>
    <a href="/reports">Reports</a>
  </div>
</div>

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

import { Popover } from '@headlessui/react'
import { ChevronDownIcon } from '@heroicons/react/20/solid'

function MyPopover() {
  return (
    <Popover>
      <Popover.Button>
        Solutions
        <ChevronDownIcon className="ui-open:rotate-180 ui-open:transform" />
      </Popover.Button>
      <Popover.Panel>
        <a href="/insights">Insights</a>
        <a href="/automations">Automations</a>
        <a href="/reports">Reports</a>
      </Popover.Panel>
    </Popover>
  )
}

Positioning the panel

To get your Popover to actually render a floating panel near your button, you'll need to use some styling technique that relies on CSS, JS, or both. In the previous example we used CSS absolute and relative positioning so that the panel renders near the button that opened it.

For more sophisticated approaches, you might use a library like Popper JS. Here we use Popper's usePopper hook to render our Popover.Panel as a floating panel near the button.

import { useState } from 'react'
import { Popover } from '@headlessui/react'
import { usePopper } from 'react-popper'

function MyPopover() {
  let [referenceElement, setReferenceElement] = useState()
  let [popperElement, setPopperElement] = useState()
  let { styles, attributes } = usePopper(referenceElement, popperElement)
  return (
    <Popover>
      <Popover.Button ref={setReferenceElement}>Solutions</Popover.Button>

      <Popover.Panel
        ref={setPopperElement}
        style={styles.popper}
        {...attributes.popper}
      >
        {/* ... */}
      </Popover.Panel>
    </Popover>
  )
}

Showing/hiding the popover

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

import { Popover } from '@headlessui/react'

function MyPopover() {
  return (
    <Popover>
      <Popover.Button>Solutions</Popover.Button>

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

If you'd rather handle this yourself (perhaps because you need to add an extra wrapper element for one reason or another), you can pass a static prop to the Popover.Panel to tell it to always render, and then use the open render prop to control when the panel is shown/hidden yourself.

import { Popover } from '@headlessui/react'

function MyPopover() {
  return (
    <Popover>
      {({ open }) => (
        <>
          <Popover.Button>Solutions</Popover.Button>

          {open && (
            <div>
              {/*
                Using the `static` prop, the `Popover.Panel` is always
                rendered and the `open` state is ignored.
              */}
              <Popover.Panel static>{/* ... */}</Popover.Panel>
            </div>
          )}
        </>
      )}
    </Popover>
  )
}

Closing popovers manually

Since popovers can contain interactive content like form controls, we can't automatically close them when you click something inside of them like we can with Menu components.

To close a popover manually when clicking a child of its panel, render that child as a Popover.Button. You can use the as prop to customize which element is being rendered.

import { Popover } from '@headlessui/react'
import MyLink from './MyLink'

function MyPopover() {
  return (
    <Popover>
      <Popover.Button>Solutions</Popover.Button>
      <Popover.Panel>
        <Popover.Button as={MyLink} href="/insights">
          Insights
        </Popover.Button>
        {/* ... */}
      </Popover.Panel>
    </Popover>
  )
}

Alternatively, Popover and Popover.Panel expose a close() render prop which you can use to imperatively close the panel, say after running an async action:

import { Popover } from '@headlessui/react'

function MyPopover() {
  return (
    <Popover>
      <Popover.Button>Terms</Popover.Button>
      <Popover.Panel>
        {({ close }) => (
          <button
            onClick={async () => {
              await fetch('/accept-terms', { method: 'POST' })
              close()
            }}
          >
            Read and accept
          </button>
        )}
      </Popover.Panel>
    </Popover>
  )
}

By default the Popover.Button receives focus after calling close(), but you can change this by passing a ref into close(ref).

Adding an overlay

If you'd like to style a backdrop over your application UI whenever you open a Popover, use the Popover.Overlay component:

import { Popover } from '@headlessui/react'

function MyPopover() {
  return (
    <Popover>
      {({ open }) => (
        <>
          <Popover.Button>Solutions</Popover.Button>
          <Popover.Overlay className="fixed inset-0 bg-black opacity-30" />

          <Popover.Panel>{/* ... */}</Popover.Panel>
        </>
      )}
    </Popover>
  )
}

In this example, we put the Popover.Overlay before the Panel in the DOM so that it doesn't cover up the panel's contents.

But like all the other components, Popover.Overlay is completely headless, so how you style it is up to you.

Transitions

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

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

function MyPopover() {
  return (
    <Popover>
      <Popover.Button>Solutions</Popover.Button>

      <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"
      >
        <Popover.Panel>{/* ... */}</Popover.Panel>
      </Transition>
    </Popover>
  )
}

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

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

function MyPopover() {
  return (
    <Popover>
      {({ open }) => (
        <>
          <Popover.Button>Solutions</Popover.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` */}
            <Popover.Panel static>{/* ... */}</Popover.Panel>
          </Transition>
        </>
      )}
    </Popover>
  )
}

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

Grouping related popovers

When rendering several related Popovers, for example in a site's header navigation, use the Popover.Group component. This ensures panels stay open while users are tabbing between Popovers within a group, but closes any open panel once the user tabs outside of the group:

import { Popover } from '@headlessui/react'

function MyPopover() {
  return (
    <Popover.Group>
      <Popover>
        <Popover.Button>Product</Popover.Button>
        <Popover.Panel>{/* ... */}</Popover.Panel>
      </Popover>

      <Popover>
        <Popover.Button>Solutions</Popover.Button>
        <Popover.Panel>{/* ... */}</Popover.Panel>
      </Popover>
    </Popover.Group>
  )
}

Rendering as different elements

Popover and its subcomponents each render a default element that is sensible for that component: the Popover, Overlay, Panel and Group components all render a <div>, and the Button component renders a <button>.

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 { Popover } from '@headlessui/react'
​
let MyCustomButton = forwardRef(function (props, ref) {
  return <button className="..." ref={ref} {...props} />
})

function MyPopover() {
  return (
    <Popover as="nav">
      <Popover.Button as={MyCustomButton}>
        Solutions
      </Popover.Button>
      <Popover.Panel as="form">
        {/* ... */}
      </Popover.Panel>
    </Popover>
  )
}

Accessibility notes

Focus management

Pressing Tab on an open panel will focus the first focusable element within the panel's contents. If a Popover.Group is being used, Tab cycles from the end of an open panel's content to the next Popover's button.

Mouse interaction

Clicking a Popover.Button toggles a panel open and closed. Clicking anywhere outside of an open panel will close that panel.

Keyboard interaction

Other

Nested Popovers are supported, and all panels will close correctly whenever the root panel is closed.

All relevant ARIA attributes are automatically managed.

When to use a Popover

Here's how Popovers compare to other similar components:

• <Menu />. Popovers are more general-purpose than Menus. Menus only support very restricted content and have specific accessibility semantics. Arrow keys also navigate a Menu's items. Menus are best for UI elements that resemble things like the menus you'd find in the title bar of most operating systems. If your floating panel has images or more markup than simple links, use a Popover.

• <Disclosure />. Disclosures are useful for things that typically reflow the document, like Accordions. Popovers also have extra behavior on top of Disclosures: they render overlays, and are closed when the user either clicks the overlay (by clicking outside of the Popover's content) or presses the escape key. If your UI element needs this behavior, use a Popover instead of a Disclosure.

• <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. Popovers are more contextual, and are usually positioned near the element that triggered them.

Component API

Popover

The main Popover component.

Popover.Overlay

This can be used to create an overlay for your Popover component. Clicking on the overlay will close the Popover.

Popover.Button

This is the trigger component to toggle a Popover. You can also use this Popover.Button component inside a Popover.Panel, if you do so, then it will behave as a close button. We will also make sure to provide the correct aria-* attributes onto the button.

Popover.Panel

This component contains the contents of your Popover.

Popover.Group

Link related sibling popovers by wrapping them in a Popover.Group. Tabbing out of one Popover.Panel will focus the next popover's Popover.Button, and tabbing outside of the Popover.Group completely will close all popovers inside the group.