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:

npm install @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>
  )
}

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

import { Disclosure } from '@headlessui/react'
import { ChevronRightIcon } from '@heroicons/react/20/solid'

function MyDisclosure() {
  return (
    <Disclosure>
      {({ open }) => (
        /* Use the `open` state to conditionally change the direction of an icon. */
        <>
          <Disclosure.Button>
            Do you offer technical support?
            <ChevronRightIcon className={open ? 'rotate-90 transform' : ''} />
          </Disclosure.Button>
          <Disclosure.Panel>No</Disclosure.Panel>
        </>
      )}
    </Disclosure>
  )
}

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 Disclosure component renders when the disclosure is open:

<!-- Rendered `Disclosure` -->
<div data-headlessui-state="open">
  <button data-headlessui-state="open">Do you offer technical support?</button>
  <div data-headlessui-state="open">No</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 { Disclosure } from '@headlessui/react'
import { ChevronRightIcon } from '@heroicons/react/20/solid'

function MyDisclosure() {
  return (
    <Disclosure>
      <Disclosure.Button>
        Do you offer technical support?
        <ChevronRightIcon className="ui-open:rotate-90 ui-open:transform" />
      </Disclosure.Button>
      <Disclosure.Panel>No</Disclosure.Panel>
    </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>
          Yes! You can purchase a license that you can share with your entire
          team.
        </Disclosure.Panel>
      </Transition>
    </Disclosure>
  )
}

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

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>
              Yes! You can purchase a license that you can share with your
              entire team.
            </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>, Panel renders a <div>. By contrast, the root Disclosure component does not render an element, and instead renders its 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, Fragment } from 'react'
import { Disclosure } from '@headlessui/react'

let MyCustomButton = forwardRef(function (props, ref) {
  return <button className="..." ref={ref} {...props} />
})
function MyDisclosure() {
  return (
    <Disclosure as="div">
      <Disclosure.Button as={MyCustomButton}>
        What languages do you support?
      </Disclosure.Button>

      <Disclosure.Panel as="ul">
        <li>HTML</li>
        <li>CSS</li>
        <li>JavaScript</li>
      </Disclosure.Panel>
    </Disclosure>
  )
}

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

Command	Description
`Enter` or `Space` when a `Disclosure.Button` is focused.	Toggles panel

All relevant ARIA attributes are automatically managed.

The main Disclosure component.

Prop	Default	Description
`as`	`Fragment`	`String \| Component` The element or component the `Disclosure` should render as.
`defaultOpen`	`false`	`Boolean` Whether or not the `Disclosure` component should be open by default.

Render Prop	Description
`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.

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

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

This component contains the contents of your disclosure.

Prop	Default	Description
`as`	`div`	`String \| Component` The element or component the `Disclosure.Panel` 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 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.