Transition
Control the transition styles of conditionally rendered elements, including nested child transitions, using CSS classes.
To get started, install Headless UI via npm:
npm install @headlessui/react
The Transition
accepts a show
prop that controls whether the children should be shown or hidden, and a set of
lifecycle props (like enterFrom
and leaveTo
) that let you add CSS classes at specific phases of a transition.
import { Transition } from '@headlessui/react'
import { useState } from 'react'
function Example() {
const [isShowing, setIsShowing] = useState(false)
return (
<>
<button onClick={() => setIsShowing((isShowing) => !isShowing)}>Toggle</button>
<Transition
show={isShowing}
enter="transition-opacity duration-300"
enterFrom="opacity-0"
enterTo="opacity-100"
leave="transition-opacity duration-150"
leaveFrom="opacity-100"
leaveTo="opacity-0"
>
<div>I will fade in and out</div>
</Transition>
</>
)
}
Wrap the content that should be conditionally rendered in a Transition
component, and use the show
prop to control
whether the content should be visible or hidden.
import { Transition } from '@headlessui/react'
import { useState } from 'react'
function Example() {
const [isShowing, setIsShowing] = useState(false)
return (
<>
<button onClick={() => setIsShowing((isShowing) => !isShowing)}>Toggle</button>
<Transition show={isShowing}> <div>I will appear and disappear</div>
</Transition>
</>
)
}
By default, the transition components will render a div
element.
Use the as
prop to render the 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 { Dialog, DialogPanel, DialogTitle, Transition, TransitionChild } from '@headlessui/react'
import { forwardRef, useState } from 'react'
let MyDialogPanel = forwardRef(function (props, ref) { return <DialogPanel className="max-w-lg bg-white p-12" ref={ref} {...props} />})
function Example() {
let [isOpen, setIsOpen] = useState(true)
return (
<Transition as={Dialog} show={isOpen} onClose={() => setIsOpen(false)}> <div className="fixed inset-0 flex w-screen items-center justify-center p-4">
<TransitionChild
as={MyDialogPanel} 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"
>
<DialogTitle>Deactivate account</DialogTitle>
{/* ... */}
</TransitionChild>
</div>
</Transition>
)
}
By default, a Transition
will enter and leave instantly, which is probably not what you're looking for if you're using
this component.
To animate your enter/leave transitions, add classes that provide the styling for each phase of the transitions using these props:
enter
: Applied the entire time an element is entering. Usually you define your duration and what properties you want to transition here, for exampletransition-opacity duration-300
.enterFrom
: The starting point of the enter transition, for exampleopacity-0
if something should fade in.enterTo
: The ending point of the enter transition, for exampleopacity-100
after fading in.leave
: Applied the entire time an element is leaving. Usually you define your duration and what properties you want to transition here, for exampletransition-opacity duration-300
.leaveFrom
: The starting point of the leave transition, for exampleopacity-100
if something should fade out.leaveTo
: The ending point of the leave transition, for exampleopacity-0
after fading out.
Here's an example:
import { Transition } from '@headlessui/react'
import { useState } from 'react'
function Example() {
const [isShowing, setIsShowing] = useState(false)
return (
<>
<button onClick={() => setIsShowing((isShowing) => !isShowing)}>Toggle</button>
<Transition
show={isShowing}
enter="transition-opacity duration-300" enterFrom="opacity-0" enterTo="opacity-100" leave="transition-opacity duration-150" leaveFrom="opacity-100" leaveTo="opacity-0" >
<div>I will fade in and out</div>
</Transition>
</>
)
}
In this example, the transitioning element will take 300ms to enter (that's the duration-300
class), and will
transition the opacity property during that time (that's transition-opacity
).
It will start completely transparent before entering (that's opacity-0
in the enterFrom
phase), and fade in to
completely opaque (opacity-100
) when finished (that's the enterTo
phase).
When the element is being removed (the leave
phase), it will transition the opacity property, and spend 150ms doing it
(transition-opacity duration-150
).
It will start as completely opaque (the opacity-100
in the leaveFrom
phase), and finish as completely transparent
(the opacity-0
in the leaveTo
phase).
All of these props are optional, and will default to just an empty string.
Sometimes you need to transition multiple elements with different animations but all based on the same state. For example, say the user clicks a button to open a sidebar that slides over the screen, and you also need to fade-in a background overlay at the same time.
You can do this by wrapping the related elements with a parent Transition
component, and wrapping each child that
needs its own transition styles with a TransitionChild
component, which will automatically communicate with the parent
Transition
and inherit the parent's show
state.
import { Transition, TransitionChild } from '@headlessui/react'
function Example({ isShowing }) {
return (
/* The `show` prop controls all nested `TransitionChild` components. */
<Transition show={isShowing}> {/* Background overlay */}
<TransitionChild enter="transition-opacity ease-linear duration-300"
enterFrom="opacity-0"
enterTo="opacity-100"
leave="transition-opacity ease-linear duration-300"
leaveFrom="opacity-100"
leaveTo="opacity-0"
>
{/* ... */}
</TransitionChild>
{/* Sliding sidebar */}
<TransitionChild enter="transition ease-in-out duration-300"
enterFrom="-translate-x-full"
enterTo="translate-x-0"
leave="transition ease-in-out duration-300"
leaveFrom="translate-x-0"
leaveTo="-translate-x-full"
>
{/* ... */}
</TransitionChild> </Transition> )
}
The TransitionChild
component has the exact same API as the Transition
component, but with no show
prop, since the
show
value is controlled by the parent.
Parent Transition
components will always automatically wait for all children to finish transitioning before
unmounting, so you don't need to manage any of that timing yourself.
If you want an element to transition the very first time it's rendered, set the appear
prop to true
.
This is useful if you want something to transition in on initial page load, or when its parent is conditionally rendered.
import { Transition } from '@headlessui/react'
function Example({ isShowing }) {
return (
<Transition
appear={true} show={isShowing}
enter="transition-opacity duration-300"
enterFrom="opacity-0"
enterTo="opacity-100"
leave="transition-opacity duration-150"
leaveFrom="opacity-100"
leaveTo="opacity-0"
>
{/* Your content goes here*/}
</Transition>
)
}
Prop | Default | Description |
as | Fragment | String | Component The element or component the transition should render as. |
show | — | Boolean Whether the children should be shown or hidden. |
appear | false | Boolean Whether the transition should run on initial mount. |
unmount | true | Boolean Whether the element should be unmounted or hidden based on the show state. |
enter | — | String Classes to add to the transitioning element during the entire enter phase. |
enterFrom | — | String Classes to add to the transitioning element before the enter phase starts. |
enterTo | — | String Classes to add to the transitioning element immediately after the enter phase starts. |
leave | — | String Classes to add to the transitioning element during the entire leave phase. |
leaveFrom | — | String Classes to add to the transitioning element before the leave phase starts. |
leaveTo | — | String Classes to add to the transitioning element immediately after the leave phase starts. |
beforeEnter | — | () => void Callback which is called before we start the enter transition. |
afterEnter | — | () => void Callback which is called after we finished the enter transition. |
beforeLeave | — | () => void Callback which is called before we start the leave transition. |
afterLeave | — | () => void Callback which is called after we finished the leave transition. |
Prop | Default | Description |
as | Fragment | String | Component The element or component the transition child should render as. |
appear | false | Boolean Whether the transition should run on initial mount. |
unmount | true | Boolean Whether the element should be unmounted or hidden based on the show state. |
enter | — | String Classes to add to the transitioning element during the entire enter phase. |
enterFrom | — | String Classes to add to the transitioning element before the enter phase starts. |
enterTo | — | String Classes to add to the transitioning element immediately after the enter phase starts. |
leave | — | String Classes to add to the transitioning element during the entire leave phase. |
leaveFrom | — | String Classes to add to the transitioning element before the leave phase starts. |
leaveTo | — | String Classes to add to the transitioning element immediately after the leave phase starts. |
beforeEnter | — | () => void Callback which is called before we start the enter transition. |
afterEnter | — | () => void Callback which is called after we finished the enter transition. |
beforeLeave | — | () => void Callback which is called before we start the leave transition. |
afterLeave | — | () => void Callback which is called after we finished the leave transition. |
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.