Disclosure

A simple, accessible foundation for building custom UIs that show and hide content, like togglable accordion panels.

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

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

Disclosures are built using the Disclosure, Disclosure.Button and Disclosure.Panel components.

The button will automatically open/close the panel when clicked, and all components will receive the appropriate aria-* related attributes like aria-expanded and aria-controls.

import { Disclosure } from '@headlessui/react' function MyDisclosure() { return ( <Disclosure> <Disclosure.Button className="py-2"> Is team pricing available? </Disclosure.Button> <Disclosure.Panel className="text-gray-500"> Yes! You can purchase a license that you can share with your entire team. </Disclosure.Panel> </Disclosure> ) }

Disclosure 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 disclosure, for example the button:

import { Disclosure } from "@headlessui/react"; function MyDisclosure() { return ( <Disclosure>
{({ open }) => (
<> <Disclosure.Button> <span>Is team pricing available?</span> {/* Use the `open` render prop to rotate the icon when the panel is open */} <ChevronRightIcon
className={`${open ? "transform rotate-90" : ""}`}
/>
</Disclosure.Button> <Disclosure.Panel>{/* ... */}</Disclosure.Panel> </>; )} </Disclosure> ); }

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

import { Disclosure } from '@headlessui/react' function MyDisclosure() { return ( <Disclosure> <Disclosure.Button>Is team pricing available?</Disclosure.Button> {/* By default, this will automatically show/hide when the Disclosure.Button is pressed. */} <Disclosure.Panel>{/* ... */}</Disclosure.Panel> </Disclosure> ) }

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 Disclosure.Panel to tell it to always render, and then use the open render prop to control when the panel is shown/hidden yourself.

import { Disclosure } from '@headlessui/react' function MyDisclosure() { return ( <Disclosure>
{({ open }) => (
<> <Disclosure.Button>Is team pricing available?</Disclosure.Button>
{open && (
<div> {/* Using `static`, `Disclosure.Panel` is always rendered and ignores the `open` state. */}
<Disclosure.Panel static>{/* ... */}</Disclosure.Panel>
</div> )} </> )} </Disclosure> ) }

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

import { Disclosure } from '@headlessui/react' import MyLink from './MyLink' function MyDisclosure() { return ( <Disclosure> <Disclosure.Button>Open mobile menu</Disclosure.Button> <Disclosure.Panel>
<Disclosure.Button as={MyLink} href="/home">
Home
</Disclosure.Button>
{/* ... */} </Disclosure.Panel> </Disclosure> ) }

This is especially useful when using disclosures for things like mobile menus that contain links where you want the disclosure to close when navigating to the next page.

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

import { Disclosure } from '@headlessui/react' function MyDisclosure() { return ( <Disclosure> <Disclosure.Button>Terms</Disclosure.Button> <Disclosure.Panel>
{({ close }) => (
<button onClick={async () => {
await fetch('/accept-terms', { method: 'POST' })
close()
}}
>
Read and accept </button> )} </Disclosure.Panel> </Disclosure> ) }

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

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

import { Disclosure, Transition } from '@headlessui/react' function MyDisclosure() { return ( <Disclosure> <Disclosure.Button>Is team pricing available?</Disclosure.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"
>
<Disclosure.Panel>{/* ... */}</Disclosure.Panel>
</Transition>
</Disclosure> ) }

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

import { Disclosure, Transition } from '@headlessui/react' function MyDisclosure() { return ( <Disclosure>
{({ open }) => (
<>
<Disclosure.Button>Is team pricing available?</Disclosure.Button> {/* Use the Transition + open render prop argument to add transitions. */}
<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"
>
{/* Don't forget to add `static` to your Disclosure.Panel! */}
<Disclosure.Panel static>{/* ... */}</Disclosure.Panel>
</Transition>
</>
)}
</Disclosure> ) }

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

Disclosure and its subcomponents each render a default element that is sensible for that component: the Button renders a <button>, Panelrenders a <div>, and interestingly the root Disclosure component does not render an extra element, and instead renders its children directly by default.

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

import { Fragment } from 'react' import { Disclosure } from '@headlessui/react' function MyDisclosure() { return ( /* Render a `div` for the root Disclosure component */
<Disclosure as="div">
{/* Render a `Fragment` for the Button component */}
<Disclosure.Button as={Fragment}>
<button>Solutions</button> </Disclosure.Button> {/* Render a `ul` for the Panel component */}
<Disclosure.Panel as="ul">{/* ... */}</Disclosure.Panel>
</Disclosure> ) }

Clicking a Disclosure.Button toggles the Disclosure's panel open and closed.

CommandDescription

Enter or Space when a Disclosure.Button is focused.

Toggles panel

All relevant ARIA attributes are automatically managed.

The main Disclosure component.

PropDefaultDescription
asFragment
String | Component

The element or component the Disclosure should render as.

defaultOpenfalse
Boolean

Whether or not the Disclosure component should be open by default.

Render PropDescription
open

Boolean

Whether or not the disclosure is open.

close

(ref?: ref | HTMLElement) => void

Closes the disclosure and refocuses Disclosure.Button. Optionally pass in a ref or HTMLElement to focus that element instead.

The trigger component that toggles a Disclosure.

PropDefaultDescription
asbutton
String | Component

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

Render PropDescription
open

Boolean

Whether or not the disclosure is open.

This component contains the contents of your disclosure.

PropDefaultDescription
asdiv
String | Component

The element or component the Disclosure.Panel 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.

Render PropDescription
open

Boolean

Whether or not the disclosure is open.

close

(ref?: ref | HTMLElement) => void

Closes the disclosure and refocuses Disclosure.Button. Optionally pass in a ref or HTMLElement to focus that element instead.

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.