Popover

Popovers are perfect for floating panels with arbitrary content like navigation menus, mobile menus and flyout menus.

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

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

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.

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

Popover and its related components expose a render prop containing the open state of the panel. You can use this to conditionally apply styles to any part of your Popover, for example the button:

import { Popover } from '@headlessui/react' import { ChevronRightIcon } from '@heroicons/react/solid' function MyPopover() { return ( <Popover>
{({ open }) => (
<> <Popover.Button> <span>Solutions</span> <ChevronRightIcon
className={`${open ? 'transform rotate-90' : ''}`}
/>
</Popover.Button> <Popover.Panel>{/* ... */}</Popover.Panel> </> )} </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, this 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 `static`, `Popover.Panel` is always rendered and
ignores the `open` state.
*/}
<Popover.Panel static>{/* ... */}</Popover.Panel>
</div>
)}
</> )} </Popover> ) }

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={`${
open ? 'opacity-30 fixed inset-0' : 'opacity-0'
} bg-black`}
/>
<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. Also, since the Popover.Overlay is always rendered (even when the panel is closed), we use the open render prop to only make it full-screen (via fixed and inset-0) when the panel is open.

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

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

Our built-in components communicate with eachother, if you require more control over the behaviour, then you can use a more explicit version:

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.

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

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

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

import { Popover } from '@headlessui/react' function MyPopover() { return ( /* Render a `nav` instead of a `div` */
<Popover as="nav">
<Popover.Button>Solutions</Popover.Button> {/* Render a `form` instead of a `div` */}
<Popover.Panel as="form">{/* ... */}</Popover.Panel>
</Popover> ) }

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.

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

CommandDescription

Enter or Space when a Popover.Button is focused.

Toggle panel

Esc

Closes any open Popovers

Tab

Cycle through an open panel's contents

Tabbing out of an open panel will close that panel, and tabbing from one open panel to a sibling Popover's button (within a Popover.Group) closes the first panel

Shift + Tab

Cycle backwards through the focus order

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

All relevant ARIA attributes are automatically managed.

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.

The main Popover component.

PropDefaultDescription
asdiv
String | Component

The element or component the Popover should render as.

Render PropDescription
open

Boolean

Whether or not the popover is open.

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

PropDefaultDescription
asdiv
String | Component

The element or component the Popover.Overlay should render as.

Render PropDescription
open

Boolean

Whether or not the popover is open.

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.

PropDefaultDescription
asbutton
String | Component

The element or component the Popover.Button should render as.

Render PropDescription
open

Boolean

Whether or not the popover is open.

This component contains the contents of your Popover.

PropDefaultDescription
asdiv
String | Component

The element or component the Popover.Panel should render as.

focusfalse
Boolean

This will force focus inside the Popover.Panel when the Popover is open. It will also close the Popover if focus left this component.

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.

Render PropDescription
open

Boolean

Whether or not the popover is open.

This allows you to wrap multiple elements and Popover's inside a group.

  • When you tab out of a Popover.Panel, it will focus the next Popover.Button in line.
  • If focus left the Popover.Group it will close all the Popover's.
PropDefaultDescription
asdiv
String | Component

The element or component the Popover.Group should render as.

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.