Troubleshoot scroll reveal animations
Find the symptom in the list. Each section gives the possible causes, and links to the page with the fix.
The content never shows
Section titled “The content never shows”- An ancestor with
overflowclips the element fully. The element never enters the visible area, so it does not reveal. Play the entrance by hand. - In
reveal(), the start state moves the element out of the visible area. The element waits at its start state. If an ancestor clips that box fully, the element does not reveal. See The start state moves the box ofreveal(). - In React, Vue and Astro,
whenisfalse. The element stays transparent untilwhenbecomestrue. See Reveal from your state.
If no script attaches the element, the content shows after 5 seconds. See The 5 second hold.
The content reveals too late or too early
Section titled “The content reveals too late or too early”- In
reveal(), the start state moves the element. A start state withx,y,scaleorrotateand noopacity: 0changes the box that the viewport check uses. Your own keyframes change it when the first keyframe has a transform. See The start state moves the box ofreveal(). - A cascade has many children. The last children start late or out of view. Reveal each item.
- The
delayis long. Keep it short. See Delay the entrance.
The content shows, then hides again
Section titled “The content shows, then hides again”The script attached the element after the 5 second hold of the stylesheet. Lazy hydration is the usual cause. See The 5 second hold.
Hydrate the reveal content eagerly:
- React or Vue in an Astro island: use
client:load, notclient:visible. - Vue and Nuxt: do not use lazy hydration for components with a reveal.
Focus can also cause it. Server markup shows while focus is in it, and the hold continues after a blur. This is on purpose.
The content shows before the entrance
Section titled “The content shows before the entrance”- The JavaScript API does not hide content before your script runs. Server-rendered content shows, then animates. See The JavaScript API.
- The page does not load the stylesheet. Some setups need a step. See Hidden in the server HTML.
- A Content Security Policy blocks the stylesheet in Astro. See Content Security Policy.
- Your styles use
!important. An inlineopacityor ananimationwith!importantcan show the element too early. See Things to know.
The content also shows immediately when the user asks for reduced motion, prints the page or turns off JavaScript. This is on purpose. See When the stylesheet does not hide content.
The content shows with no animation
Section titled “The content shows with no animation”- The user asks for reduced motion. See Reduced motion.
- Focus moved into the element before or during the entrance. Focus reveals a waiting element immediately, and it finishes a running entrance. See Focus.
- The browser rejected an option. An invalid easing or duration shows the element with no animation. See Errors.
- A cascade child cannot animate. In React, Vue and Astro, a child that you add after the reveal shows with no animation. An Astro island or an Astro
Revealas a direct child of a cascade does not get the entrance of the cascade. See Things to know. In the JavaScript API, a child that you add after thecascade()call shows with no animation. See Targets. - In Astro, the HTML parser moved the element. See Where to place a reveal.
- The browser is too old. See Older browsers.
The element loses its own styles
Section titled “The element loses its own styles”- The entrance replaces the element’s own values of the animated properties. An example is a
rotateor anopacitythat your CSS sets. Put the value on an inner element, or use an additive keyframe. - In React, Vue and Astro, the stylesheet replaces your own
animationuntil the reveal. Put your animation on an inner element. See Things to know. - Two calls reveal the same element. The later entrance replaces the earlier entrance. See Do not reveal one element two times.
The element jumps at the end of the entrance
Section titled “The element jumps at the end of the entrance”The last keyframe is different from the resting style of the element. See End at the resting style.
Your code waits for animations that never finish
Section titled “Your code waits for animations that never finish”A waiting entrance of reveal() or cascade() never finishes. An animation of your own that repeats forever also never finishes. See Wait for the end of the entrance.
The build fails
Section titled “The build fails”Global CSS cannot be imported from within node_modules. The Next.js Pages Router with webpack needs a step. See Set up the Pages Router with webpack.
Errors in the console
Section titled “Errors in the console”- An invalid easing, duration or threshold. The browser rejects the option, and core reports the error of the browser. See Errors.
- An invalid CSS selector.
reveal()andcascade()throw aSyntaxError. See Errors. The HTML parser moved the element out of <awesome-reveal>. In Astro, the reveal is in a place that the HTML parser does not accept. See Where to place a reveal.getReveal() needs the element that Reveal or Cascade rendered. In Astro, the element is not the tag thatRevealorCascaderendered, or the HTML parser moved the tag. Pass the rendered tag, not an ancestor or a child. SeegetReveal.
Get help
Section titled “Get help”If this page does not solve your problem, search the issues of the packages repo. To ask a question, open a discussion. To report a bug, open an issue with a minimal example.