Dialog (Modal)

A fully-managed, renderless dialog component jam-packed with accessibility and keyboard features, perfect for building completely custom modal and dialog windows for your next application.

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

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

Dialogs are built using the Dialog, Dialog.Overlay, Dialog.Title and Dialog.Description components.

When the dialog's open prop is true, the contents of the dialog will render. Focus will be moved inside the dialog and trapped there as the user cycles through the focusable elements. Scroll is locked, the rest of your application UI is hidden from screen readers, and clicking outside the dialog or pressing the Escape key will call the onClose function and close the dialog.

import { useState } from 'react' import { Dialog } from '@headlessui/react' function MyDialog() { let [isOpen, setIsOpen] = useState(true) return ( <Dialog open={isOpen} onClose={() => setIsOpen(false)}> <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> ) }

Dialogs have no automatic management of their open/closed state. To show and hide your dialog, pass React state into the open prop. When open is true the dialog will render, and when it's false the dialog will unmount.

The onClose callback fires when an open dialog is dismissed, which happens when the user clicks outside the contents of your dialog or presses the Escape key. You can use this callback to set open back to false and close your dialog.

import { useState } from 'react' import { Dialog } from '@headlessui/react' function MyDialog() { // The open/closed state lives outside of the Dialog and is managed by you
let [isOpen, setIsOpen] = useState(true)
function handleDeactivate() { // ... } return ( /* Pass `isOpen` to the `open` prop, and use `onClose` to set the state back to `false` when the user clicks outside of the dialog or presses the escape key. */
<Dialog open={isOpen} onClose={() => setIsOpen(false)}>
<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> {/* You can render additional buttons to dismiss your dialog by setting `isOpen` to `false`. */}
<button onClick={() => setIsOpen(false)}>Cancel</button>
<button onClick={handleDeactivate}>Deactivate</button> </Dialog> ) }

For accessibility reasons, your dialog should contain at least one focusable element. By default, the Dialog component will focus the first focusable element (by DOM order) once its rendered, and pressing the Tab key will cycle through all additional focusable elements within the contents.

Focus is trapped within the dialog as long as its rendered, so tabbing to the end will start cycling back through the beginning again. All other application elements outside of the dialog will be marked as inert and thus not focusable.

If you'd like something other than the first focusable element to receive initial focus when your dialog is initially rendered, you can use the initialFocus ref:

import { useState, useRef } from 'react' import { Dialog } from '@headlessui/react' function MyDialog() { let [isOpen, setIsOpen] = useState(true)
let completeButtonRef = useRef(null)
function completeOrder() { // ... } return ( /* Use `initialFocus` to force initial focus to a specific ref. */ <Dialog
initialFocus={completeButtonRef}
open={isOpen} onClose={() => setIsOpen(false)} >
<Dialog.Overlay /> <Dialog.Title>Complete your order</Dialog.Title> <p>Your order is all ready!</p> <button onClick={() => setIsOpen(false)}>Cancel</button>
<button ref={completeButtonRef} onClick={completeOrder}>
Complete order </button> </Dialog> ) }

Typically modal dialogs will be rendered on top of a transparent dark background. You can style the Dialog.Overlay component to achieve this look.

The overlay component accepts normal React props like style and className, so you can style it using any technique you like. Be sure to place it before the rest of your dialog's contents in the DOM so it doesn't obscure your content's interactive elements.

import { useState } from 'react' import { Dialog } from '@headlessui/react' function Example() { let [isOpen, setIsOpen] = useState(true) return ( <Dialog open={isOpen} onClose={() => setIsOpen(false)} className="fixed z-10 inset-0 overflow-y-auto" > {/* Use the overlay to style a dim backdrop for your dialog */}
<Dialog.Overlay className="fixed inset-0 bg-black opacity-30" />
{/* ... */} </Dialog> ) }

There's nothing special about the contents of your dialog – you can use whatever HTML and CSS you please. Typical dialogs will have a max width and be centered in the screen, as in the example below, but fullscreen treatments on smaller screens are also common.

import { useState } from 'react' import { Dialog } from '@headlessui/react' function Example() { let [isOpen, setIsOpen] = useState(true) return ( <Dialog open={isOpen} onClose={() => setIsOpen(false)} className="fixed z-10 inset-0 overflow-y-auto" > <div className="flex items-center justify-center min-h-screen"> <Dialog.Overlay className="fixed inset-0 bg-black opacity-30" /> <div className="bg-white rounded max-w-sm mx-auto"> <Dialog.Title>Complete your order</Dialog.Title> {/* ... */} </div> </div> </Dialog> ) }

For accessibility reasons, you should use the Dialog.Title and Dialog.Description components when rendering content that labels and describes your dialog contents. They will be automatically linked to the root Dialog component via the aria-labelledby and aria-describedby attributes, and their contents will be announced to users using screenreaders.

import { useState } from 'react' import { Dialog } from '@headlessui/react' function MyDialog() { let [isOpen, setIsOpen] = useState(true) return ( <Dialog open={isOpen} onClose={() => setIsOpen(false)}> <Dialog.Overlay /> {/* Use the Title and Description components when appropriate to improve the accessibility of your custom dialogs. */}
<Dialog.Title>Deactivate account</Dialog.Title>
<Dialog.Description>
This will permanently deactivate your account
</Dialog.Description>
{/* ... */} </Dialog> ) }

If you've ever implemented a Dialog before, you've probably come across Portals in React. Portals let you invoke components from one place in the DOM (for instance deep within your applicaiton UI), but actually render to another place in the DOM entirely.

Since Dialogs and their overlays take up the full page, you typically want to render them as a sibling to the root-most node of your React application. That way you can rely on natural DOM ordering to ensure that their content is rendered on top of your existing application UI. This also makes it easy to apply scroll locking to the rest of your application, as well as ensure that your Dialog's contents and overlay are unobstructed to receive focus and click events.

Because of these accessibility concerns, Headless UI's Dialog component actually uses a Portal under-the-hood. This way we can provide features like unobstructed event handling and making the rest of your application inert. So, when using our Dialog, there's no need to use a Portal yourself! We've already taken care of it.

To animate the opening/closing of the dialog, use the Transition component. All you need to do is wrap the Dialog in a <Transition>, and dialog will transition automatically based on the state of the show prop on the <Transition>.

When using <Transition> with your dialogs, you can remove the open prop, as the dialog will read the show state from the <Transition> automatically.

import { useState } from 'react' import { Dialog, Transition } from '@headlessui/react' function MyDialog() { let [isOpen, setIsOpen] = useState(true) return (
<Transition
show={isOpen}
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"
>
<Dialog onClose={() => setIsOpen(false)}> <Dialog.Overlay /> <Dialog.Title>Deactivate account</Dialog.Title> {/* ... */} </Dialog>
</Transition>
) }

To animate the Dialog's overlay and contents separately, use Transition and Transition.Child:

import { useState, Fragment } from 'react' import { Dialog, Transition } from '@headlessui/react' function MyDialog() { let [isOpen, setIsOpen] = useState(true) return ( // Use the `Transition` component at the root level
<Transition show={isOpen} as={Fragment}>
<Dialog onClose={() => setIsOpen(false)}> {/* Use one Transition.Child to apply one transition to the overlay... */}
<Transition.Child
as={Fragment}
enter="ease-out duration-300"
enterFrom="opacity-0"
enterTo="opacity-100"
leave="ease-in duration-200"
leaveFrom="opacity-100"
leaveTo="opacity-0"
>
<Dialog.Overlay /> </Transition.Child> {/* ...and another Transition.Child to apply a separate transition to the contents. */}
<Transition.Child
as={Fragment}
enter="ease-out duration-300"
enterFrom="opacity-0 scale-95"
enterTo="opacity-100 scale-100"
leave="ease-in duration-200"
leaveFrom="opacity-100 scale-100"
leaveTo="opacity-0 scale-95"
>
<Dialog.Title>Deactivate account</Dialog.Title> {/* ... */} </Transition.Child> </Dialog> </Transition> ) }

If you want to animate your dialogs using another animation library like Framer Motion or React Spring and need more control, you can use the static prop to tell Headless UI not to manage rendering itself, and control it manually with another tool:

import { useState } from 'react' import { Dialog } from '@headlessui/react' import { AnimatePresence, motion } from 'framer-motion' function MyDialog() { let [isOpen, setIsOpen] = useState(true) return ( // Use the `Transition` component + show prop to add transitions.
<AnimatePresence>
{open && (
<Dialog
static
as={motion.div}
open={isOpen}
onClose={() => setIsOpen(false)} > <Dialog.Overlay /> <Dialog.Title>Deactivate account</Dialog.Title> {/* ... */} </Dialog> )}
</AnimatePresence>
) }

The open prop is still used for manage scroll locking and focus trapping, but as long as static is present, the actual element will always be rendered regardless of the open value, which allows you to control it yourself externally.

When the Dialog's open prop is true, the contents of the Dialog will render and focus will be moved inside the Dialog and trapped there. The first focusable element according to DOM order will receive focus, although you can use the initialFocus ref to control which element receives initial focus. Pressing Tab on an open Dialog cycles through all the focusable elements.

When a Dialog is rendered, clicking the Dialog.Overlay will close the Dialog.

No mouse interaction to open the Dialog is included out-of-the-box, though typically you will wire a <button /> element up with an onClick handler that toggles the Dialog's open prop to true.

CommandDescription

Esc

Closes any open Dialogs

Tab

Cycles through an open Dialog's contents

Shift + Tab

Cycles backwards through an open Dialog's contents

When a Dialog is open, scroll is locked and the rest of your application UI is hidden from screen readers.

All relevant ARIA attributes are automatically managed.

The main Dialog component.

PropDefaultDescription
open
Boolean

Whether the Dialog is open or not.

onClose
(false) => void

Called when the Dialog is dismissed (via the overlay or Escape key). Typically used to close the dialog by setting open to false.

initialFocus
React.MutableRefObject

A ref to an element that should receive focus first.

asdiv
String | Component

The element or component the Dialog should render as.

staticfalse
Boolean

Whether the element should ignore the internally managed open/closed state.

unmounttrue
Boolean

Whether the element should be unmounted or hidden based on the open/closed state.

Render PropDescription
open

Boolean

Whether or not the dialog is open.

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

PropDefaultDescription
asdiv
String | Component

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

Render PropDescription
open

Boolean

Whether or not the dialog is open.

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

PropDefaultDescription
ash2
String | Component

The element or component the Dialog.Title should render as.

Render PropDescription
open

Boolean

Whether or not the dialog is open.

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

PropDefaultDescription
asp
String | Component

The element or component the Dialog.Description should render as.

Render PropDescription
open

Boolean

Whether or not the dialog is open.

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.