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.
Two code paths
Section titled “Two code paths”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()andcascade()create the entrance when you call them, and pause it at its start. Until the reveal,reveal()holds the element, andcascade()holds each direct child, at the first keyframe.
The entrance is a native animation
Section titled “The entrance is a native animation”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().
The viewport check
Section titled “The viewport check”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.
One entrance for each element
Section titled “One entrance for each element”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.
Errors
Section titled “Errors”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
SyntaxErrorofquerySelectorAll().
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.
Do not reveal one element two times
Section titled “Do not reveal one element two times”Give each element to one call only. If two calls reveal the same element, the later entrance replaces the earlier entrance.