Skip to content

How scroll reveal animations work

Awesome Reveal uses two APIs of the browser. The Intersection Observer API tells when an element enters the viewport. The Web Animations API plays the entrance. For the cost of this work, see Performance.

All packages use @awesome-reveal/core. A waiting element works in one of two ways:

  • React, Vue and Astro: the stylesheet of the package hides the waiting element with opacity: 0, at its resting position. The package creates the entrance at the reveal. See Server rendering.
  • The JavaScript API: reveal() and cascade() create the entrance when you call them, and pause it at its start. Until the reveal, reveal() holds the element, and cascade() holds each direct child, at the first keyframe.

Each entrance is one call to element.animate(), with the duration and the delay of the options. The call also sets fill: "backwards", so the element keeps its first keyframe during the delay.

The from option gives two keyframes: the start state and the resting state. The keyframes set only the properties of the start state. The keyframes option replaces the generated keyframes.

A start state with opacity: 0 and a movement, such as each side, gives a third keyframe. The first keyframe has opacity: 0 at the resting position, and the movement starts immediately after it. For the effect on the viewport check, see The start state moves the box of reveal().

Each element has its own observer. cascade() and Cascade observe the container, and animate its direct children.

The observer reports two thresholds: 0 and the value of the threshold option. The report at 0 tells that the element entered the viewport, also when it cannot reach the threshold. Thus tall elements and small scroll containers still reveal.

Focus in a waiting element also reveals it. See Accessibility.

At the reveal, the observer stops. The entrance plays one time, and it has no exit animation. In React, Vue and Astro, use when to play it again.

In the JavaScript API, each element releases its observer and its event listeners when its entrances finish. The element keeps its resting style. To stop all the elements of a call before that, call dispose() on the handle that reveal() or cascade() returns.

In React, Vue and Astro, the observer stops also when the element leaves the page.

reveal() and cascade() do not throw for an invalid option. The browser validates the options:

  • If the browser rejects an easing or a duration, the element shows with no animation.
  • If the browser rejects the threshold, the entrance plays immediately.
  • The browser ignores an invalid CSS value in a keyframe, and reports nothing.
  • An invalid CSS selector throws the SyntaxError of querySelectorAll().

Core reports the errors of the browser from a microtask. Thus the console and your error tracker get them, but they do not stop your code. Core reports each message one time on a page. WebKit gives the same message to different easing and duration errors. Fix the first error, then reload the page to see the next error.

Give each element to one call only. If two calls reveal the same element, the later entrance replaces the earlier entrance.