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.

Please note that this library only supports Vue 3.

npm install @headlessui/vue

Disclosures are built using the Disclosure, DisclosureButton and DisclosurePanel 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.

<template>
  <Disclosure>
    <DisclosureButton class="py-2">
      Is team pricing available?
    </DisclosureButton>
    <DisclosurePanel class="text-gray-500">
      Yes! You can purchase a license that you can share with your entire team.
    </DisclosurePanel>
  </Disclosure>
</template>

<script setup>
  import {
    Disclosure,
    DisclosureButton,
    DisclosurePanel,
  } from '@headlessui/vue'
</script>

Disclosure and its related components expose a scoped slot 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:

<template>
  <Disclosure v-slot="{ open }">
    <DisclosureButton class="py-2">
      <span>Is team pricing available?</span>

      <!-- Use the `open` slot prop to rotate the icon when the panel is open -->
      <ChevronRightIcon :class='open ? "transform rotate-90" : ""' />
    </DisclosureButton>
    <DisclosurePanel>
      <!-- ... -->
    </DisclosurePanel>
  </Disclosure>
</template>

<script setup>
  import {
    Disclosure,
    DisclosureButton,
    DisclosurePanel,
  } from '@headlessui/vue'
  import { ChevronRightIcon } from '@heroicons/vue/solid'
</script>

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

<template>
  <Disclosure>
    <DisclosureButton>Is team pricing available?</DisclosureButton>

    <!--
      By default, this will automatically show/hide when the
      DisclosureButton is pressed.
    -->
    <DisclosurePanel>
      <!-- ... -->
    </DisclosurePanel>
  </Disclosure>
</template>

<script setup>
  import {
    Disclosure,
    DisclosureButton,
    DisclosurePanel,
  } from '@headlessui/vue'
</script>

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

<template>
  <Disclosure v-slot="{ open }">
    <DisclosureButton>Is team pricing available?</DisclosureButton>

    <div v-show="open">
      <!--
        Using `static`, `DisclosurePanel` is always rendered and
        ignores the `open` state.
      -->
      <DisclosurePanel static>
        <!-- ... -->
      </DisclosurePanel>
    </div>
  </Disclosure>
</template>

<script setup>
  import {
    Disclosure,
    DisclosureButton,
    DisclosurePanel,
  } from '@headlessui/vue'
</script>

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

<template>
  <Disclosure>
    <DisclosureButton>Open mobile menu</DisclosureButton>
    <DisclosurePanel>
      <DisclosureButton :as="MyLink" href="/home">Home</DisclosureButton>
      <!-- ... -->
    </DisclosurePanel>
  </Disclosure>
</template>

<script setup>
  import {
    Disclosure,
    DisclosureButton,
    DisclosurePanel,
  } from '@headlessui/vue'
  import MyLink from './MyLink'
</script>

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 DisclosurePanel expose a close() slot prop which you can use to imperatively close the panel, say after running an async action:

<template>
  <Disclosure>
    <DisclosureButton>Terms</DisclosureButton>
    <DisclosurePanel v-slot="{ close }">
      <button @click="accept(close)">Read and accept</button>
    </DisclosurePanel>
  </Disclosure>
</template>

<script setup>
  import {
    Disclosure,
    DisclosureButton,
    DisclosurePanel,
  } from '@headlessui/vue'

  async function accept(close) {
    await fetch('/accept-terms', { method: 'POST' })
    close()
  }</script>

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

To animate the opening/closing of your Disclosure's panel, you can use Vue's built-in <transition> component. All you need to do is wrap your DisclosurePanelin a <transition>, and the transition will be applied automatically.

<template>
  <Disclosure>
    <DisclosureButton>Is team pricing available?</DisclosureButton>

    <!-- Use the built-in <transition> component to add transitions. -->
    <transition
      enter-active-class="transition duration-100 ease-out"
      enter-from-class="transform scale-95 opacity-0"
      enter-to-class="transform scale-100 opacity-100"
      leave-active-class="transition duration-75 ease-out"
      leave-from-class="transform scale-100 opacity-100"
      leave-to-class="transform scale-95 opacity-0"
    >
      <DisclosurePanel>
        <!-- ... -->
      </DisclosurePanel>
    </transition>
  </Disclosure>
</template>

<script setup>
  import {
    Disclosure,
    DisclosureButton,
    DisclosurePanel,
  } from '@headlessui/vue'
</script>

If you'd like to coordinate multiple transitions for different children of your Disclosure, check out the Transition component included in Headless UI.

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.

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

<template>
  <!-- Render a `div` for the root Disclosure component -->
  <Disclosure as="div">
    <!-- Don't render any element (only children) for the Button component -->
    <DisclosureButton as="template">
      <button>Solutions</button>
    </DisclosureButton>

    <!-- Render a `ul` for the Panel component -->
    <DisclosurePanel as="ul"><!-- ... --></DisclosurePanel>
  </Disclosure>
</template>

<script setup>
  import {
    Disclosure,
    DisclosureButton,
    DisclosurePanel,
  } from '@headlessui/vue'
</script>

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

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

All relevant ARIA attributes are automatically managed.

The main Disclosure component.

Prop	Default	Description
`as`	`template`	`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.

Slot Prop	Description
`open`	`Boolean` Whether or not the disclosure is open.
`close`	`(ref?: ref \| HTMLElement) => void` Closes the disclosure and refocuses `DisclosureButton`. 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 `DisclosureButton` should render as.

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

Slot Prop	Description
`open`	`Boolean` Whether or not the disclosure is open.
`close`	`(ref?: ref \| HTMLElement) => void` Closes the disclosure and refocuses `DisclosureButton`. 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.