Multiple new components

[RobinMalfait]

This PR adds a few new components:

• Dialog
• Disclosure
• FocusTrap
• Popover
• Portal
• Switch.Description (This adds an aria-describedby to the Switch component)

This PR also has a few fixes and perforamnce improvements:

• Internally we use useReducer a lot, and state updates were always causing re-renders. Now we will only re-render when something actually changed. This change has not been applied to all components yet, but didn't want to bloat the scope to much in this very big PR
• "outside click" had a few regression, I applied fixes to the Menu and Listbox components
• Improvements on the internal useSyncRefs, we created a new callback when the refs changed, but they changed always
• Introduced an internal set of utilities for focus management

---

Disclosure component

A component for showing/hiding content.

Disclosure

<Disclosure>
  <Disclosure.Button>Toggle</Disclosure.Button>
  <Disclosure.Panel>Contents</Disclosure.Panel>
</Disclosure>

Props

Prop	Type	Default	Description
as	String | Component	React.Fragment (no wrapper element)	The element or component the Disclosure should render as.

Render prop object

Prop	Type	Description
open	Boolean	Whether or not the disclosure is open.

Disclosure.Button

Props

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

Render prop object

Prop	Type	Description
open	Boolean	Whether or not the disclosure is open.

Disclosure.Panel

Props

Prop	Type	Default	Description
as	String | Component	div	The element or component the Disclosure.Panel should render as.
static	Boolean	false	Whether the element should ignore the internally managed open/closed state.
unmount	Boolean	true	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 object

Prop	Type	Description
open	Boolean	Whether or not the disclosure is open.

---

FocusTrap component

A component for making sure that you can't Tab out of the contents of this
component.

Focus strategy:

• An initialFocus prop can be passed in, this is a ref object, which is a ref to the element that should receive initial focus.
• If an input element exists with an autoFocus prop, it will receive initial focus.
• If none of those exists, it will try and focus the first focusable element.
• If that doesn't exist, it will throw an error.

Once the FocusTrap will unmount, the focus will be restored to the element that was focused before the FocusTrap was rendered.

FocusTrap

<FocusTrap>
  <form>
    <input type="email" name="Email" />
    <input type="password" name="password" />
    <button>Submit</button>
  </form>
</FocusTrap>

Props

Prop	Type	Default	Description
as	String | Component	div	The element or component the FocusTrap should render as.
initialFocus	React.MutableRefObject	undefined	A ref to an element that should receive focus first.

---

Portal component

A component for rendering your contents within a Portal (at the end of document.body).

Portal

<Portal>
  <p>This will be rendered inside a Portal, at the end of `document.body`</p>
</Portal>

---

Dialog component

This component can be used to render content inside a Dialog/Modal. This contains a ton of features:

1. Renders inside a Portal
2. Controlled component
3. Uses FocusTrap with its features (Focus first focusable element, autoFocus or initialFocus ref)
4. Adds a scroll lock
5. Prevents content jumps by faking your scrollbar width
6. Marks other elements as inert (hides other elements from screen readers)
7. Closes on escape
8. Closes on click outside
9. Once the Dialog becomes hidden (e.g.: md:hidden) it will also trigger the onClose

Dialog

function Example() {
  let [isOpen, setIsOpen] = useState(true)

  return (
    <Dialog open={isOpen} onClose={setIsOpen}>
      <Dialog.Overlay />

      <Dialog.Title>Deactivate account</Dialog.Title>
      <Dialog.Description>This will permanently deactivate your account</Dialog.Description>

      <p>
        Are you sure you want to deactivate your account? All of your data will be permanently
        removed. This action cannot be undone.
      </p>

      <button onClick={() => setIsOpen(false)}>Deactivate</button>
      <button onClick={() => setIsOpen(false)}>Cancel</button>
    </Dialog>
  )
}

Props

Prop	Type	Default	Description
open	Boolean	/	Wether the Dialog is open or not.
onClose	Function	/	Called when the Dialog should close. For convenience we pass in a onClose(false) so that you can use: onClose={setIsOpen}.
initialFocus	React.MutableRefObject	/	A ref to an element that should receive focus first.
as	String | Component	div	The element or component the Dialog should render as.
static	Boolean	false	Whether the element should ignore the internally managed open/closed state.
unmount	Boolean	true	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 object

Prop	Type	Description
open	Boolean	Whether or not the dialog is open.

Dialog.Overlay

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

Props

Prop	Type	Default	Description
as	String | Component	div	The element or component the Dialog.Overlay should render as.

Render prop object

Prop	Type	Description
open	Boolean	Whether or not the disclosure is open.

Dialog.Title

This is the title for your Dialog. When this is used, it will set the aria-labelledby on the Dialog.

Props

Prop	Type	Default	Description
as	String | Component	h2	The element or component the Dialog.Title should render as.

Render prop object

Prop	Type	Description
open	Boolean	Whether or not the disclosure is open.

Dialog.Description

This is the description for your Dialog. When this is used, it will set the aria-describedby on the Dialog.

Props

Prop	Type	Default	Description
as	String | Component	p	The element or component the Dialog.Description should render as.

Render prop object

Prop	Type	Description
open	Boolean	Whether or not the disclosure is open.

---

Popover component

This component can be used for navigation menu's, mobile menu's and flyout menu's.

Popover

<Popover.Group>
  <Popover>
    <Popover.Button>Solutions</Popover.Button>
    <Popover.Panel>
      <a href="#">Analytics</a>
      <a href="#">Engagement</a>
      <a href="#">Security</a>
      <a href="#">Integrations</a>
      <a href="#">Automations</a>
    </Popover.Panel>
  </Popover>

  <a href="#">Pricing</a>
  <a href="#">Docs</a>

  <Popover>
    <Popover.Button>More</Popover.Button>
    <Popover.Panel focus>
      <a href="#">Help Center</a>
      <a href="#">Guides</a>
      <a href="#">Events</a>
      <a href="#">Security</a>
    </Popover.Panel>
  </Popover>
</Popover.Group>

Props

Prop	Type	Default	Description
as	String | Component	div	The element or component the Popover should render as.

Render prop object

Prop	Type	Description
open	Boolean	Whether or not the dialog is open.

Popover.Overlay

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

Props

Prop	Type	Default	Description
as	String | Component	div	The element or component the Popover.Overlay should render as.

Render prop object

Prop	Type	Description
open	Boolean	Whether or not the disclosure is open.

Popover.Button

This is the trigger component to open 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.

Props

Prop	Type	Default	Description
as	String | Component	button	The element or component the Popover.Button should render as.

Render prop object

Prop	Type	Description
open	Boolean	Whether or not the disclosure is open.

Popover.Panel

This component contains the contents of your Popover.

Props

Prop	Type	Default	Description
as	String | Component	div	The element or component the Popover.Panel should render as.
focus	Boolean	false	This will force focus inside the Popover.Panel when the Popover is open. It will also close the Popover if focus left this component.
static	Boolean	false	Whether the element should ignore the internally managed open/closed state.
unmount	Boolean	true	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 object

Prop	Type	Description
open	Boolean	Whether or not the disclosure is open.

Popover.Group

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.

Props

Prop	Type	Default	Description
as	String | Component	div	The element or component the Popover.Group should render as.

[vercel]

This pull request is being automatically deployed with Vercel (learn more).
To see the status of your deployments, click below or on the icon next to each commit.

headlessui-react – ./packages/@headlessui-react

🔍 Inspect: https://vercel.com/tailwindlabs/headlessui-react/q8qu5m3kp
✅ Preview: https://headlessui-react-git-multiple-components.tailwindlabs.vercel.app

headlessui-vue – ./packages/@headlessui-vue

🔍 Inspect: https://vercel.com/tailwindlabs/headlessui-vue/p4r4zyvz3
✅ Preview: https://headlessui-vue-git-multiple-components.tailwindlabs.vercel.app

[Zertz]

This looks very promising! If the work isn't quite ready and you can spare the time, do you think it would be possible to release a beta on npm?

[RobinMalfait]

@Zertz You can already try it using npm install @headlessui/react@dev or yarn add @headlessui/react@dev.