This is the full developer documentation for Awesome Reveal
# Scroll reveal animations
> Fade, slide, zoom and stagger elements as they scroll into view. One core with no dependencies runs in React, Vue, Astro and plain JavaScript.
## Fade in from any side
Choose `top`, `right`, `bottom` or `left`. The element fades in and slides 24 pixels from that side. You set one prop and write no CSS.
```jsx
```
## Zoom, rotate and blur on scroll
Pass an object to set the start state. Mix opacity, offset, scale, rotation and blur. The entrance ends at full opacity and size, with no offset, rotation or blur.
```jsx
```
## Staggered animations in one line
Wrap a list in `Cascade`, and its children enter one after another. Set the gap with `interval`, in milliseconds. Use it for grids, menus, logos and feature lists.
```jsx
{tiles.map((tile) => (
))}
```
## Reveal headings word by word
Wrap each word in an element, and `Cascade` reveals the words in order. Give them `display: inline-block`, because a transform does not move an inline box.
```jsx
Everyword{" "}
getsits{" "}
ownentrance
```
## Your keyframes, native speed
Need a flip, a bounce or a 3D turn? Pass native Web Animations keyframes. The browser can run opacity and transforms off the main thread, so the motion stays smooth.
```jsx
{cards}
```
## Trigger animations on demand
Not everything waits for a scroll. Set `when` to `true` to play the entrance, and to `false` to reset it. Connect it to tabs, steps, toasts or any state you own. Add `hidden` to hide the content from screen readers too.
```jsx
Changes saved
```
## Know the moment it shows
Each reveal calls `onReveal`, also with reduced motion. Send an analytics event, load more data or start a counter, as this demo does. In Astro, listen for the `reveal` event.
```jsx
track("pricing_seen")}>
```
## Accessible and SEO friendly by default
Each package does all four with no configuration. You get all of this, and a lot more, from a core of less than 2 kB with no dependencies.
* ### SEO friendly
Search engines and screen readers read all of your content. It is in the HTML before any animation plays.
* ### No flicker on load
With the React, Vue and Astro packages, content does not blink into view before its entrance. If the script fails, it shows after 5 seconds.
* ### Respects motion settings
Visitors who ask their device for reduced motion see the content at once, with no animation.
* ### Fast and smooth
Pages stay light, and the motion runs smoothly. The browser does the work with its own APIs, so no animation library ships to your visitors.
## Start in under a minute
Pick your framework, install one package and wrap an element. Each package includes skills for AI agents. All four packages share the same core, the same entrance options and TypeScript types.
* React
```shell
pnpm add @awesome-reveal/react
```
```jsx
import { Reveal } from "@awesome-reveal/react";
export const Hero = () => (
```
[Astro scroll animations](/frameworks/astro/)
* JavaScript
```shell
pnpm add @awesome-reveal/core
```
```js
import { reveal } from "@awesome-reveal/core";
reveal("h1", { from: "left" });
```
[JavaScript scroll animations](/frameworks/javascript/)
[Read the docs ](/getting-started/) Copy prompt
# Accessible scroll animations
> How Awesome Reveal respects prefers-reduced-motion, reveals focused content immediately, keeps waiting content for screen readers, and prints all content.
An entrance is decorative motion. All content must work without it. Awesome Reveal never removes content from the page, and it shows the content immediately when the motion can cause a problem.
## Reduced motion
[Section titled “Reduced motion”](#reduced-motion)
If the user asks for [reduced motion](https://developer.mozilla.org/en-US/docs/Web/CSS/Reference/At-rules/@media/prefers-reduced-motion), all the content shows immediately, with no animation and no delay:
* In React, Vue and Astro, the stylesheet does not hide the content, and the package reveals each element when it attaches it.
* In the JavaScript API, `reveal()` and `cascade()` create no animations.
If the preference changes to reduced motion while the page is open, core cancels the waiting and the running entrances, and the content shows. For reduced motion and `when`, see [Hide the content](/guides/manual-control/#hide-the-content). For `onReveal` and the `reveal` event with reduced motion, see [Run code when the reveal starts](/guides/reveal-events/#run-code-when-the-reveal-starts).
To test, emulate `prefers-reduced-motion` in the developer tools of your browser.
## Focus
[Section titled “Focus”](#focus)
Focus in a waiting element reveals it immediately, with no entrance. Thus a keyboard user does not focus invisible content. Focus in a waiting cascade container reveals all its children.
Focus during the [delay](/guides/timing/#delay-the-entrance) or the entrance finishes the entrance immediately. In a cascade, focus in the container also finishes the entrances of the children that wait for their interval.
In React, Vue and Astro, server markup also shows while focus is in it, before the script attaches it. See [The 5 second hold](/concepts/server-rendering/#the-5-second-hold).
In React, Vue and Astro, focus does not reveal an element while `when` is `false`.
## Screen readers
[Section titled “Screen readers”](#screen-readers)
A waiting element stays in the accessibility tree, so screen readers read it, and the keyboard can focus its controls. Do not put information in the motion only.
To hide content from all users, see [Hide the content](/guides/manual-control/#hide-the-content).
## Print
[Section titled “Print”](#print)
Waiting content shows in print:
* In React, Vue and Astro, the stylesheet hides content only on screens.
* In the JavaScript API, core moves each waiting entrance to its end before the print. After the print, the entrance waits again.
Core uses the [`beforeprint`](https://developer.mozilla.org/en-US/docs/Web/API/Window/beforeprint_event) and [`afterprint`](https://developer.mozilla.org/en-US/docs/Web/API/Window/afterprint_event) events. The print emulation in developer tools does not fire these events. To test the JavaScript API, open the print preview of your browser.
# How scroll reveal animations work
> How Awesome Reveal animates elements on scroll with the Intersection Observer and Web Animations APIs: paused entrances, one-time reveals and errors.
Awesome Reveal uses two APIs of the browser. The [Intersection Observer API](https://developer.mozilla.org/en-US/docs/Web/API/Intersection_Observer_API) tells when an element enters the viewport. The [Web Animations API](https://developer.mozilla.org/en-US/docs/Web/API/Web_Animations_API) plays the entrance. For the cost of this work, see [Performance](/concepts/performance/).
## Two code paths
[Section titled “Two code paths”](#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](/concepts/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.
## The entrance is a native animation
[Section titled “The entrance is a native animation”](#the-entrance-is-a-native-animation)
Each entrance is one call to [`element.animate()`](https://developer.mozilla.org/en-US/docs/Web/API/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`](/guides/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()`](/guides/timing/#the-start-state-moves-the-box-of-reveal).
## The viewport check
[Section titled “The viewport check”](#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`](/guides/timing/#reveal-later-with-a-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](/guides/timing/#tall-elements-and-small-scroll-containers) still reveal.
Focus in a waiting element also reveals it. See [Accessibility](/concepts/accessibility/#focus).
## One entrance for each element
[Section titled “One entrance for each element”](#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`](/guides/manual-control/#play-the-entrance-again) 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”](#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 `SyntaxError` of [`querySelectorAll()`](https://developer.mozilla.org/en-US/docs/Web/API/Document/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.
## Do not reveal one element two times
[Section titled “Do not reveal one element two times”](#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.
# Scroll animation performance
> Why Awesome Reveal animations stay smooth: compositor animations, no scroll listeners and a core of less than 2 kB gzipped, plus advice on will-change.
Awesome Reveal gives the work to the browser. The browser runs the viewport check and the animation, so the library runs no code on each scroll or on each frame.
## Animations on the compositor
[Section titled “Animations on the compositor”](#animations-on-the-compositor)
Without `blur`, the generated entrance animates only `opacity`, `translate`, `scale` and `rotate`. These are [the properties that the compositor runs](/guides/keyframes/#animate-the-properties-that-the-compositor-runs). For the cases that run on the main thread, see [a start state with `blur`](/guides/entrances/#things-to-know) and [an additive keyframe](/guides/keyframes/#keep-the-elements-own-values).
## No scroll listeners
[Section titled “No scroll listeners”](#no-scroll-listeners)
Core adds no `scroll` event listener. The browser runs the viewport check, and the [Intersection Observer API](https://developer.mozilla.org/en-US/docs/Web/API/Intersection_Observer_API) calls core only when the visible fraction of an element crosses a threshold.
## Do not add `will-change`
[Section titled “Do not add will-change”](#do-not-add-will-change)
Do not add [`will-change`](https://developer.mozilla.org/en-US/docs/Web/CSS/Reference/Properties/will-change) for a reveal. The browser treats an animated property as if `will-change` already names it.
## Bundle size
[Section titled “Bundle size”](#bundle-size)
`@awesome-reveal/core` has no dependencies. With `reveal()` and `cascade()`, it adds less than 2 kB gzipped to your bundle.
A [test in the packages repo](https://github.com/awesome-reveal/awesome-reveal/blob/next/packages/core/test/package/tree-shaking.test.ts) checks this size on each change. The test bundles an import of `reveal()` and `cascade()` with a Vite production build, which minifies the code. Then it compresses the bundle with gzip. The size applies only to `@awesome-reveal/core`. The React, Vue and Astro packages use another entry of core, `@awesome-reveal/core/adapter`.
# Server rendering without a flash
> How the React, Vue and Astro packages of Awesome Reveal hide content in the server HTML, and how a 5 second hold shows the content when no script runs.
A server-rendered page shows its HTML before the scripts run. If a script hides the content, the content shows, then hides, then animates. The React, Vue and Astro packages hide the waiting content in the server HTML, so it does not flash.
## Hidden in the server HTML
[Section titled “Hidden in the server HTML”](#hidden-in-the-server-html)
Each waiting element has the `data-awesome-reveal` attribute in the server HTML:
* `Reveal` and the other reveal APIs set `data-awesome-reveal="hidden"` on the element.
* `Cascade` and the other cascade APIs set `data-awesome-reveal="cascade"` on the container.
The `reveal.css` stylesheet of the package gives `opacity: 0` to each hidden element and to the direct children of each cascade container. The element keeps its size and its place, so the layout does not move at the reveal. At the reveal, the package removes the attribute, and the entrance starts.
The modules of each package import the stylesheet, so your bundler or Astro adds it to the page. Three setups need a step:
* [React or Vue in an Astro island](/frameworks/react-vue-astro/#import-the-stylesheet)
* [The Next.js Pages Router with webpack](/frameworks/nextjs/#set-up-the-pages-router-with-webpack)
* [The Nuxt development server](/frameworks/vue-ssr-nuxt/#add-the-stylesheet-in-development)
## The 5 second hold
[Section titled “The 5 second hold”](#the-5-second-hold)
The stylesheet does not hide a waiting element with a static rule. It plays the `awesome-reveal-hold` CSS animation, which holds `opacity: 0` for 5 seconds. When the script of the package attaches the element, it adds the `data-awesome-reveal-attached` attribute. A static `opacity: 0` rule then hides the element until the reveal.
If no script attaches the element in 5 seconds, the hold ends, and the content shows. Thus the content does not stay hidden when a script fails to load or throws.
While focus is in the element or in the cascade container, the content shows. Thus a keyboard user does not focus invisible content before the script attaches it. After a blur, the hold continues until its 5 seconds end.
If the script attaches the element after 5 seconds, the content shows, then hides again until it reveals. Lazy hydration often attaches the element that late. Hydrate the reveal content eagerly.
## When the stylesheet does not hide content
[Section titled “When the stylesheet does not hide content”](#when-the-stylesheet-does-not-hide-content)
The stylesheet hides content only for the `screen` media type, and only with [`prefers-reduced-motion: no-preference`](https://developer.mozilla.org/en-US/docs/Web/CSS/Reference/At-rules/@media/prefers-reduced-motion). Thus the content shows immediately in these cases:
* The user asks for [reduced motion](/concepts/accessibility/#reduced-motion).
* The user [prints the page](/concepts/accessibility/#print).
* JavaScript is off. A [`scripting: none`](https://developer.mozilla.org/en-US/docs/Web/CSS/Reference/At-rules/@media/scripting) rule stops the hold. In browsers without the `scripting` media feature, such as Safari 16, the content shows after 5 seconds.
## Things to know
[Section titled “Things to know”](#things-to-know)
* **The hold replaces your own `animation` until the reveal.** Put your own animation on an inner element. The hold also fires `animationstart` and `animationend` events, and shows in `getAnimations()`.
* **`!important` styles can show the element too early.** An inline `opacity` or your own `animation` with `!important` can show the element before the reveal.
* **The packages reserve two attributes.** Do not set `data-awesome-reveal` or `data-awesome-reveal-attached` yourself.
* **The stylesheet does not reach a shadow root.** It cannot hide an element in a shadow root.
## The JavaScript API
[Section titled “The JavaScript API”](#the-javascript-api)
`@awesome-reveal/core` has no stylesheet, and it does not hide content before your script calls `reveal()` or `cascade()`. Server-rendered content can show, then animate. For server-rendered pages, use the React, Vue or Astro package.
You can import core on the server. Call `reveal()` and `cascade()` only in the browser.
## Search engines
[Section titled “Search engines”](#search-engines)
The content is in the server HTML. The stylesheet changes only the `opacity` of the content, not the text or the layout. Thus a search engine or a tool that reads the HTML gets all the content.
# Astro scroll animations without hydration
> Add scroll animations to Astro with no client directive: where to place Reveal, and how it works with ClientRouter, transition:persist, server islands and CSP.
Use `@awesome-reveal/astro` to add scroll animations to Astro 6 and 7 sites. [Install the package](/getting-started/#install-the-package), and import `Reveal` and [`Cascade`](/guides/lists/) in your `.astro` files. The package does not use a UI framework, so it needs no [`client:*` directive](https://docs.astro.build/en/reference/directives-reference/#client-directives) and no stylesheet import:
```astro
---
import { Cascade, Reveal } from "@awesome-reveal/astro";
---
Scroll animations in Astro
Fast
Small
Accessible
```
## How it works in Astro
[Section titled “How it works in Astro”](#how-it-works-in-astro)
Each `Reveal` and `Cascade` renders its tag inside an `awesome-reveal` [custom element](https://developer.mozilla.org/en-US/docs/Web/API/Web_components/Using_custom_elements). The custom element has `display: contents`, so it does not change the layout. But the child combinator (`>`), `:nth-child()` and `parentElement` see it. To control the entrance from a client script, use [`getReveal`](/reference/astro/#getreveal).
Astro adds the stylesheet and a small module script of the package to the page. The stylesheet hides the waiting elements in the server HTML. The script defines the custom element, and the custom element attaches its tag to the viewport observer. Without JavaScript, the content shows.
## Where to place a reveal
[Section titled “Where to place a reveal”](#where-to-place-a-reveal)
The HTML parser moves some tags out of the `awesome-reveal` element. Obey these rules:
* Do not put `Reveal` or `Cascade` directly in a `