Skip to content

Troubleshoot scroll reveal animations

Find the symptom in the list. Each section gives the possible causes, and links to the page with the fix.

  • An ancestor with overflow clips 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 of reveal().
  • In React, Vue and Astro, when is false. The element stays transparent until when becomes true. See Reveal from your state.

If no script attaches the element, the content shows after 5 seconds. See The 5 second hold.

  • In reveal(), the start state moves the element. A start state with x, y, scale or rotate and no opacity: 0 changes 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 of reveal().
  • A cascade has many children. The last children start late or out of view. Reveal each item.
  • The delay is long. Keep it short. See Delay the entrance.

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, not client: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 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 inline opacity or an animation with !important can 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 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 Reveal as 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 the cascade() 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 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.

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.

  • 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() and cascade() throw a SyntaxError. 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 that Reveal or Cascade rendered, or the HTML parser moved the tag. Pass the rendered tag, not an ancestor or a child. See getReveal.

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.