Migrate from react-awesome-reveal v4
Version 5 of react-awesome-reveal changes the API on purpose. It replaces the effect components and Emotion with the Reveal and Cascade components and native Web Animations. Do the steps on this page to migrate your code.
Choose the package
Section titled “Choose the package”You can use one of these packages. The two packages give the same API.
@awesome-reveal/react. Use it for a new project, and to get all future versions.react-awesome-revealv5. It re-exports@awesome-reveal/react, so you can keep thereact-awesome-revealimport path.
pnpm add @awesome-reveal/react# or, to keep the import path:pnpm add react-awesome-revealCheck the requirements
Section titled “Check the requirements”- React 18 or 19.
- A bundler or a runtime that loads ES modules. The packages are ES modules only.
- If no other code uses Emotion, remove it. Version 5 does not use Emotion.
Replace the effect components
Section titled “Replace the effect components”Reveal is a named export. Version 4 also had a default export.
import { Reveal } from "@awesome-reveal/react";Replace each effect component with Reveal, and set from. from names the side where the element starts. In v4, left and right also name that side, but up and down name the movement. So up becomes a start on the bottom side.
A side in from moves the element 24 pixels. The v4 effects moved it by its full size, so this table gives the v4 start position. To use the shorter v5 motion, set from to the side, for example from="bottom".
The generated entrance has a different easing and duration than v4. To keep the v4 duration, set duration={1000}.
| v4 | from with the v4 start position |
|---|---|
<Fade> |
{ opacity: 0 } |
<Fade direction="up"> |
{ opacity: 0, y: "100%" } |
<Fade direction="down"> |
{ opacity: 0, y: "-100%" } |
<Fade direction="left"> |
{ opacity: 0, x: "-100%" } |
<Fade direction="right"> |
{ opacity: 0, x: "100%" } |
<Fade direction="top-left"> |
{ opacity: 0, x: "-100%", y: "-100%" } |
<Fade direction="top-right"> |
{ opacity: 0, x: "100%", y: "-100%" } |
<Fade direction="bottom-left"> |
{ opacity: 0, x: "-100%", y: "100%" } |
<Fade direction="bottom-right"> |
{ opacity: 0, x: "100%", y: "100%" } |
<Fade big direction="up"> |
{ opacity: 0, y: 2000 } |
<Slide> or <Slide direction="left"> |
{ x: "-100%" } |
<Slide direction="right"> |
{ x: "100%" } |
<Slide direction="up"> |
{ y: "100%" } |
<Slide direction="down"> |
{ y: "-100%" } |
<Zoom> |
{ opacity: 0, scale: 0.3 } |
<Rotate> |
{ opacity: 0, rotate: -200 } |
A <Reveal> with no keyframes |
{ opacity: 0, x: "-100%" } |
The big prop with down, left or right also moves the element 2000 pixels, on the applicable axis.
For Bounce, Flip, Hinge, JackInTheBox, Roll and AttentionSeeker, and for Zoom or Rotate with a direction, use native keyframes. See the next section.
Change Emotion keyframes into native keyframes
Section titled “Change Emotion keyframes into native keyframes”Version 4 took Emotion keyframes. Version 5 takes an array of native keyframe objects. Change each step of the CSS animation into an object:
- Put the percentage of the step in
offset, from 0 to 1. - Put the
animation-timing-functionof the step ineasing. v4 usedeasefor each step with no timing function of its own. A keyframe with noeasingis linear. - Make the last keyframe agree with the resting style of the element.
import { Reveal } from "@awesome-reveal/react";
<Reveal keyframes={[ { opacity: 0, transform: "scale(0.3)", easing: "ease" }, { opacity: 1, offset: 0.5, easing: "ease" }, { opacity: 1, transform: "none" }, ]}> Zoom in</Reveal>;These keyframes give the exact v4 Zoom entrance, which reaches full opacity at the middle. The from value in the table above fades over the full entrance. See Use your own keyframes.
Update the props
Section titled “Update the props”| v4 | v5 |
|---|---|
cascade |
The Cascade component. For a list, render the list with Cascade, for example <Cascade as="ul">. |
damping |
interval on Cascade. Set it to the v4 duration * damping, in milliseconds. |
duration |
duration. The default is 600 milliseconds. The v4 default was 1000. |
delay |
delay, in milliseconds. In a cascade, it moves the start of the whole sequence. |
fraction |
threshold. |
triggerOnce |
Remove it. The entrance plays one time. To play it again, set when to false, then to true. |
direction, big |
from. See the table above. |
keyframes |
keyframes, with native keyframes. |
className, style |
They apply to the one element that Reveal renders. |
childClassName, childStyle |
Style the children directly. |
onVisibilityChange |
onReveal. It gets the element, one time for each reveal. |
reverse |
No replacement. Version 5 has no exit animations. |
This example shows a v4 cascade and its v5 version:
import { Fade } from "react-awesome-reveal";
<Fade direction="up" cascade damping={0.1} triggerOnce> <p>One</p> <p>Two</p></Fade>;import { Cascade } from "@awesome-reveal/react";
<Cascade from={{ opacity: 0, y: "100%" }} duration={1000} interval={100}> <p>One</p> <p>Two</p></Cascade>;Behavior changes
Section titled “Behavior changes”The type check does not find these changes. Check them after the migration:
- One element.
Revealrenders one element around its children, andassets its tag. Version 4 wrapped each element child in adiv, and animated eachliof a list child. - One observer. One observer watches the whole
Reveal, so all its children reveal together. For a long list, use oneRevealfor each item. Cascadedoes not split text. To reveal each word, wrap each word in an element. See Animate a list.- A new easing. The generated entrance uses
cubic-bezier(0.22, 1, 0.36, 1). To change it, use native keyframes. - One play. The entrance plays one time. In v4, it played each time by default.
Also check the refs, the hydration, reduced motion and the teardown.
Set up the stylesheet
Section titled “Set up the stylesheet”The package loads its stylesheet automatically. Two setups need a step:
-
Next.js Pages Router with webpack. Add
@awesome-reveal/reacttotranspilePackages. Add it also when you install onlyreact-awesome-reveal.next.config.mjs export default { transpilePackages: ["@awesome-reveal/react"] }; -
Astro island. Import
reveal.cssin the page or the layout, from the package that you install:react-awesome-reveal/reveal.cssor@awesome-reveal/react/reveal.css.
The Next.js App Router and Turbopack need no step.
Migrate with an agent
Section titled “Migrate with an agent”The migrating-from-v4 skill teaches a coding agent all the changes from v4. To get it, see Agent skills.