This is the abridged 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 Every word{" "} gets its{" "} own entrance ``` ## 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 ``` ## 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 = () => (

Hello

); ``` [React scroll animations](/frameworks/react/) * Vue ```shell pnpm add @awesome-reveal/vue ``` ```vue ``` [Vue scroll animations](/frameworks/vue/) * Astro ```shell pnpm add @awesome-reveal/astro ``` ```astro --- import { Reveal } from "@awesome-reveal/astro"; ---

Hello

``` [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 ``, a table section, a row or a `

    Reveal{" "} a part of the text .

    ``` If the parser moves the tag, the browser console shows an error. After a few seconds, the tag shows with no entrance. `as` does not accept the document tags (`html`, `head` and `body`), the table parts or the SVG-only tags. TypeScript rejects them. ## View transitions [Section titled “View transitions”](#view-transitions) Reveals work with the [``](https://docs.astro.build/en/guides/view-transitions/), with no setup. After a navigation, each new `awesome-reveal` element attaches itself. An element with [`transition:persist`](https://docs.astro.build/en/guides/view-transitions/#maintaining-state) keeps its state. If it revealed before the navigation, its entrance does not play again. Put `transition:persist` on an ancestor, or directly on `Reveal`: ```astro Reveals one time across navigations ``` The package does not need the `astro:page-load` event. Your own scripts that call [`getReveal`](/reference/astro/#getreveal) need it, because the `` does not run a [processed ` ``` A [prerendered page](https://developer.mozilla.org/en-US/docs/Web/API/Speculation_Rules_API) does not animate until the browser activates it. ## Server islands [Section titled “Server islands”](#server-islands) A `Reveal` inside a [server island](https://docs.astro.build/en/guides/server-islands/) reveals when Astro adds the island to the page. You do not need a step: ```astro --- import ServerTime from "../components/ServerTime.astro"; ---

    Loading...

    ``` src/components/ServerTime.astro ```astro --- import { Reveal } from "@awesome-reveal/astro"; --- Rendered at {new Date().toLocaleTimeString()} ``` ## Content Security Policy [Section titled “Content Security Policy”](#content-security-policy) The package writes no `style` attribute, no inline script and no CSS at runtime. But Astro can put the package stylesheet and your scripts inline in the HTML. Use one of these setups: * Set [`security.csp`](https://docs.astro.build/en/reference/configuration-reference/#securitycsp) to `true`. Astro adds a `` policy with hashes for the inline styles and scripts that it adds. Astro does not support this option with the ``. * Send your own policy, such as `style-src 'self'; script-src 'self'`, and set [`build.inlineStylesheets`](https://docs.astro.build/en/reference/configuration-reference/#buildinlinestylesheets) to `'never'`. Also make sure that the built HTML has no inline ` ``` src/pages/index.astro ```astro --- import "@awesome-reveal/vue/reveal.css"; import FeatureList from "../components/FeatureList.vue"; --- ``` The stylesheet hides the waiting elements in the server HTML. The package imports it only in the browser build. Astro gets the CSS of a page from the server build, so it does not add the stylesheet of an island. Without the import, the content shows before the reveal. ## Hydrate the island with client:load [Section titled “Hydrate the island with client:load”](#hydrate-the-island-with-clientload) The server HTML hides each waiting element until the island hydrates, for at most 5 seconds. See [The 5 second hold](/concepts/server-rendering/#the-5-second-hold). [`client:visible`](https://docs.astro.build/en/reference/directives-reference/#clientvisible) hydrates the island when it enters the viewport. That is often after 5 seconds, so the content shows, then hides. Use [`client:load`](https://docs.astro.build/en/reference/directives-reference/#clientload). ## Islands in a Cascade [Section titled “Islands in a Cascade”](#islands-in-a-cascade) The [`Cascade`](/guides/lists/) of `@awesome-reveal/astro` does not animate an island that is its direct child. An island has `display: contents`. Wrap each island in an element: ```astro --- import { Cascade } from "@awesome-reveal/astro"; import Card from "../components/Card.jsx"; ---
  • ``` # Vue scroll animations > Add scroll animations to Vue 3.5: fade and slide elements in with Reveal, stagger a list with Cascade, and reveal your own elements with the v-reveal directive. Use `@awesome-reveal/vue` to add scroll animations to a Vue app. An element fades and slides in when it scrolls into view. The package does not link an animation to the scroll position, as a parallax effect or a scroll progress bar does. ## Install the package [Section titled “Install the package”](#install-the-package) ```shell pnpm add @awesome-reveal/vue ``` For the supported Vue versions, see [Requirements](/getting-started/#requirements). ## Reveal an element on scroll [Section titled “Reveal an element on scroll”](#reveal-an-element-on-scroll) Wrap the element in `Reveal`: ```vue ``` `Reveal` renders an element around its default slot. [`as`](/reference/options/#as) sets its tag, and [`from`](/guides/entrances/) sets the entrance. To fade, zoom, rotate or blur the element in, set a [start state](/guides/entrances/#zoom-rotate-and-blur-with-a-start-state). ## Stagger a list with Cascade [Section titled “Stagger a list with Cascade”](#stagger-a-list-with-cascade) `Cascade` reveals its direct children one after the other: ```vue ``` For a long list or a tall grid, see [Animate a list](/guides/lists/#reveal-a-long-list-or-a-tall-grid). ## Reveal your own element with a directive [Section titled “Reveal your own element with a directive”](#reveal-your-own-element-with-a-directive) `v-reveal` and `v-cascade` reveal an element that you render, with no wrapper element. In ` ``` To use the directives with no import, [register them for all components](/frameworks/vue-ssr-nuxt/#register-the-directives-for-all-components). ## Control the reveal from state [Section titled “Control the reveal from state”](#control-the-reveal-from-state) To play the entrance when your state changes, such as when a panel opens, give [`when`](/guides/manual-control/). To run code when the element reveals, listen to the [`reveal` event](/guides/reveal-events/) of `Reveal` and `Cascade`, or give `onReveal` to `v-reveal`. ## Server rendering [Section titled “Server rendering”](#server-rendering) To prevent a flash of the content before hydration, see [Server rendering](/concepts/server-rendering/). * For Nuxt, see [Nuxt and Vue SSR scroll animations](/frameworks/vue-ssr-nuxt/). * For a Vue island in Astro, see [React and Vue scroll animations in Astro](/frameworks/react-vue-astro/). ## Next steps [Section titled “Next steps”](#next-steps) * [Use your own keyframes](/guides/keyframes/): give native Web Animations keyframes. * [Change the timing](/guides/timing/): set the duration, the delay and the threshold. * [Vue API](/reference/vue/): all the components, directives and types. # Nuxt and Vue SSR scroll animations > Add scroll animations to Nuxt and Vue SSR apps: hide content in the server HTML, register v-reveal in a Nuxt plugin, and prevent a flash after lazy hydration. Use `@awesome-reveal/vue` to add scroll animations to a Nuxt app or to your own [Vue SSR](https://vuejs.org/guide/scaling-up/ssr.html) setup. [Install the package](/getting-started/#install-the-package), and import it in your components. Server rendering needs no setup. The Nuxt development server needs one line of config. ## Server rendering [Section titled “Server rendering”](#server-rendering) `Reveal`, [`Cascade`](/guides/lists/), `v-reveal` and `v-cascade` render the waiting element hidden in the server HTML. The package stylesheet hides it, so the content does not flash before the script runs. Your bundler adds the stylesheet to the page. Hydration attaches the element to the viewport observer, with no hydration mismatch. With [`:when="true"`](/guides/manual-control/), the server still renders the element hidden. The entrance plays after hydration. ## Use it in Nuxt [Section titled “Use it in Nuxt”](#use-it-in-nuxt) Import the components and the directives in your components, as in any Vue app: app/pages/index.vue ```vue ``` ### Register the directives for all components [Section titled “Register the directives for all components”](#register-the-directives-for-all-components) To use `v-reveal` and `v-cascade` with no import, register them in a [Nuxt plugin](https://nuxt.com/docs/4.x/directory-structure/app/plugins). The `GlobalDirectives` declaration lets TypeScript check the values of the directives: app/plugins/awesome-reveal.ts ```ts import { vCascade, vReveal } from "@awesome-reveal/vue"; export default defineNuxtPlugin((nuxtApp) => { nuxtApp.vueApp.directive("reveal", vReveal); nuxtApp.vueApp.directive("cascade", vCascade); }); declare module "vue" { interface GlobalDirectives { vReveal: typeof vReveal; vCascade: typeof vCascade; } } ``` In a Vue app without Nuxt, call [`app.directive("reveal", vReveal)`](https://vuejs.org/api/application.html#app-directive) on your app. ### Add the stylesheet in development [Section titled “Add the stylesheet in development”](#add-the-stylesheet-in-development) The production build of Nuxt adds the package stylesheet to the server HTML. The development server adds it only after the page loads, so the content can show for a moment before it hides. To get the same result as in production, add the stylesheet to the [`css`](https://nuxt.com/docs/4.x/api/nuxt-config#css) option: nuxt.config.ts ```ts export default defineNuxtConfig({ css: ["@awesome-reveal/vue/reveal.css"], }); ``` The production build adds the stylesheet one time. ## Hydrate the reveals eagerly [Section titled “Hydrate the reveals eagerly”](#hydrate-the-reveals-eagerly) The server HTML hides each waiting element until hydration attaches it, for at most 5 seconds. See [The 5 second hold](/concepts/server-rendering/#the-5-second-hold). Lazy hydration often attaches the element after 5 seconds. Examples are [`hydrateOnVisible()`](https://vuejs.org/guide/components/async.html#lazy-hydration) in Vue and the [`hydrate-on-visible`](https://nuxt.com/docs/4.x/directory-structure/app/components#delayed-or-lazy-hydration) prop of a Nuxt lazy component. Then the content shows, and hides again when the user scrolls to it. Do not use lazy hydration for components with a reveal. # Get started with scroll animations > Install Awesome Reveal for React, Vue, Astro or JavaScript, reveal your first element on scroll, and animate the items of a list one after the other. Awesome Reveal animates elements when they scroll into view. Each framework package uses the same core. The core uses the [Intersection Observer API](https://developer.mozilla.org/en-US/docs/Web/API/Intersection_Observer_API) and the [Web Animations API](https://developer.mozilla.org/en-US/docs/Web/API/Web_Animations_API) of the browser, and it has no dependencies. ## Requirements [Section titled “Requirements”](#requirements) | Framework | Framework version | Node.js | | ---------- | ----------------- | -------------- | | React | 18 or 19 | 20.19 or later | | Vue | 3.5 or later | 20.19 or later | | Astro | 6 or 7 | 22.12 or later | | JavaScript | | 20.19 or later | The packages are ES modules only. They include their TypeScript types. ## Install the package [Section titled “Install the package”](#install-the-package) Install the package for your framework. * React ```shell pnpm add @awesome-reveal/react ``` * Vue ```shell pnpm add @awesome-reveal/vue ``` * Astro ```shell pnpm add @awesome-reveal/astro ``` * JavaScript ```shell pnpm add @awesome-reveal/core ``` With npm, yarn or bun, use `npm install`, `yarn add` or `bun add`, followed by the package name. ## Reveal an element [Section titled “Reveal an element”](#reveal-an-element) Wrap the element in `Reveal`. With `@awesome-reveal/core`, call `reveal()` with a CSS selector, an element or a list of elements. * React ```jsx import { Reveal } from "@awesome-reveal/react"; export function HeroTitle() { return (

    Hello

    ); } ``` * Vue ```vue ``` * Astro ```astro --- import { Reveal } from "@awesome-reveal/astro"; ---

    Hello

    ``` * JavaScript ```js import { reveal } from "@awesome-reveal/core"; reveal("h1"); ``` When the element enters the viewport, it [fades in and moves up 24 pixels](/guides/entrances/#slide-in-from-a-side). The entrance [plays one time](/guides/manual-control/#play-the-entrance-again). You do not import a stylesheet. ## Animate a list [Section titled “Animate a list”](#animate-a-list) [`Cascade`](/guides/lists/) reveals its direct children one after the other. The [`interval`](/reference/options/#interval) option sets the time between the start of two children, in milliseconds. The default is 80. * React ```jsx import { Cascade } from "@awesome-reveal/react"; export function FeatureList() { return (
  • Small
  • Native
  • Accessible
  • ); } ``` * Vue ```vue ``` * Astro ```astro --- import { Cascade } from "@awesome-reveal/astro"; ---
  • Small
  • Native
  • Accessible
  • ``` * JavaScript ```js import { cascade } from "@awesome-reveal/core"; cascade("ul.features", { interval: 120 }); ``` ## What happens when the page loads [Section titled “What happens when the page loads”](#what-happens-when-the-page-loads) * The React, Vue and Astro packages render the element as hidden in the server HTML, so the element [does not flash](/concepts/server-rendering/) before the script runs. Hydrate the reveal content eagerly. See [The 5 second hold](/concepts/server-rendering/#the-5-second-hold). * `@awesome-reveal/core` [does not hide content](/concepts/server-rendering/#the-javascript-api) before your script calls `reveal()`. * If the user asks for [reduced motion](https://developer.mozilla.org/en-US/docs/Web/CSS/Reference/At-rules/@media/prefers-reduced-motion), the content shows at once, with [no animation](/concepts/accessibility/#reduced-motion). * In [older browsers](/reference/browser-support/#older-browsers), the content does not stay hidden. React or Vue in an Astro island Hydrate the island with `client:load`, not `client:visible`. Import `@awesome-reveal/react/reveal.css` or `@awesome-reveal/vue/reveal.css` in the Astro page or layout. See [React or Vue in Astro](/frameworks/react-vue-astro/). ## Next steps [Section titled “Next steps”](#next-steps) * [Choose the entrance](/guides/entrances/): fade and slide in from a side, or zoom, rotate and blur. * [Options](/reference/options/): all the options, with their types and default values. * Frameworks: add scroll animations to [React](/frameworks/react/), [Next.js](/frameworks/nextjs/), [Vue](/frameworks/vue/), [Vue SSR and Nuxt](/frameworks/vue-ssr-nuxt/), [Astro](/frameworks/astro/) or [plain JavaScript](/frameworks/javascript/). # AI coding agent skills and llms.txt > Teach your AI coding agent the Awesome Reveal API: install the skills of each package with pnpm or the skills CLI, and read the docs as llms.txt or Markdown. A coding agent can learn Awesome Reveal from two sources: the agent skills of the packages, and a text version of these docs. To start, copy a prompt for your agent: * The [Get started](/getting-started/) page has a prompt that tells the agent to add the animations to your project. * [Migrate from v4](/guides/migrate-from-v4/) has a prompt that tells the agent to migrate your code from `react-awesome-reveal` v4. Each prompt tells the agent to install the package and to read the skill in the installed package. Thus the agent uses the skill of the version that you install. ## Agent skills [Section titled “Agent skills”](#agent-skills) Each package includes agent skills. A skill teaches a coding agent how to use the package: * **`adding-reveal-animations`** teaches the components, hooks, directives or functions of the package. `@awesome-reveal/react`, `@awesome-reveal/vue`, `@awesome-reveal/astro` and `@awesome-reveal/core` include it. * **`migrating-from-v4`** teaches the changes from `react-awesome-reveal` v4. `@awesome-reveal/react` and `react-awesome-reveal` v5 include it. `react-awesome-reveal` v4 has no skills. See [Migrate from v4](/guides/migrate-from-v4/). The skills are in the `skills` directory of each package. ### Link the skills with pnpm [Section titled “Link the skills with pnpm”](#link-the-skills-with-pnpm) [pnpm 12.11](https://pnpm.io/agent-skills) or later links the skills of a direct dependency into your project. pnpm links nothing until you approve the package. 1. Install the package. After the install, pnpm lists the packages with skills that wait for approval. 2. Approve the package: ```sh pnpm approve @awesome-reveal/react ``` pnpm writes the approval in the `permissions` setting of `pnpm-workspace.yaml`. The approval applies to all skills of the package, also in later versions: pnpm-workspace.yaml ```yaml permissions: "@awesome-reveal/react": skills: true ``` pnpm links the skills into the agent skill directories that exist in the root of your workspace, such as `.claude/skills`. When an agent that pnpm recognizes runs pnpm, pnpm also creates the skill directory of that agent. pnpm recognizes an agent from the environment variables that the agent sets. To choose the directories, set [`skills.dirs`](https://pnpm.io/settings/build#skillsdirs). If pnpm finds no directory for an approved skill, the install fails. ### Install the skills with the skills CLI [Section titled “Install the skills with the skills CLI”](#install-the-skills-with-the-skills-cli) The [`skills`](https://github.com/vercel-labs/skills) CLI gets the skills of a package from [npmx.dev](https://npmx.dev/). Thus it works with each package manager, also before you install the package. The CLI needs Node.js 22.20 or later: ```sh pnpm dlx skills add https://npmx.dev/@awesome-reveal/react ``` In the URL, use the name of your package: `@awesome-reveal/react`, `@awesome-reveal/vue`, `@awesome-reveal/astro` or `@awesome-reveal/core`. The CLI asks which skills to install, and for which agents. npmx.dev gives the skills of the `latest` version of the package on npm. For `react-awesome-reveal`, that version is v4, so use the URL of `@awesome-reveal/react` to get `migrating-from-v4`. The installed skills do not change when you update the package. To update them, run the command again. ## llms.txt [Section titled “llms.txt”](#llmstxt) The docs site gives its content as text files for language models: * [`/llms.txt`](/llms.txt): a summary of the project, with links to the two other files. * [`/llms-full.txt`](/llms-full.txt): all the docs. * [`/llms-small.txt`](/llms-small.txt): all the docs, with less detail. The files contain the current docs only. They do not contain the [v4 docs](/v4/). ## Markdown pages [Section titled “Markdown pages”](#markdown-pages) Each docs page has a Markdown version. To get it, remove the last slash of the URL, and add `.md`. For example, the Markdown version of `/guides/timing/` is `/guides/timing.md`. The Markdown version of the home page is `/index.md`. The actions at the top of each page, except the home page, also give the Markdown version: * **Copy page** copies the Markdown to the clipboard. * **View as Markdown** opens the Markdown version. On the current docs, the **Ask Claude** and **Ask ChatGPT** actions open a chat about the page. The HTML of each page links to its Markdown version with ``. # Fade, slide and zoom entrance animations > Fade and slide elements in on scroll from the top, right, bottom or left, or zoom, rotate and blur them in with a start state of the from option. The [`from`](/reference/options/#from) option sets the start state of the entrance. The element animates from this state to no offset, no rotation, no blur, a scale of 1 and an opacity of 1. ## Slide in from a side [Section titled “Slide in from a side”](#slide-in-from-a-side) Set `from` to `"top"`, `"right"`, `"bottom"` or `"left"`. The element starts transparent and 24 pixels away from its resting position, on that side. The default is `"bottom"`, so the element moves up. The distance is always 24 pixels. For a different distance, set a start state. ## Zoom, rotate and blur with a start state [Section titled “Zoom, rotate and blur with a start state”](#zoom-rotate-and-blur-with-a-start-state) Set `from` to an object. The object can have these properties: | Property | Type | A number is in | | --------- | ------------------ | -------------- | | `opacity` | `number` | | | `x` | `number \| string` | pixels | | `y` | `number \| string` | pixels | | `scale` | `number` | | | `rotate` | `number \| string` | degrees | | `blur` | `number \| string` | pixels | A string contains a CSS value with its unit, for example `"-100%"` or `"-5deg"`. The object sets the complete start state. Only the properties that you set animate. For example, `{ scale: 0.9 }` scales the element with no fade. To add a fade, also set `opacity: 0`. These start states give common entrances: | Entrance | `from` | | -------------------------- | ------------------------------- | | Fade only | `{ opacity: 0 }` | | Zoom in | `{ opacity: 0, scale: 0.8 }` | | Slide in from far away | `{ opacity: 0, y: 80 }` | | Slide in by its full width | `{ opacity: 0, x: "-100%" }` | | Slide in diagonally | `{ opacity: 0, x: -24, y: 24 }` | | Rotate in | `{ opacity: 0, rotate: -8 }` | | Blur in | `{ opacity: 0, blur: 8 }` | ## The easing [Section titled “The easing”](#the-easing) The entrance uses the easing [`cubic-bezier(0.22, 1, 0.36, 1)`](https://developer.mozilla.org/en-US/docs/Web/CSS/Reference/Values/easing-function/cubic-bezier). The `from` option cannot change it. For a different easing, [use your own keyframes](/guides/keyframes/#set-the-easing). ## Things to know [Section titled “Things to know”](#things-to-know) * **The element’s own values do not apply during the entrance.** The entrance animates the CSS properties `translate`, `scale`, `rotate`, `filter` and `opacity`, but only the properties that the start state sets. While the entrance plays, the element’s own values of these properties do not apply. In the JavaScript API, they also do not apply while the element waits. The element’s own `transform` property applies. To keep an own value, such as `rotate: 3deg`, put it on an inner element, or use the [`keyframes`](/guides/keyframes/#keep-the-elements-own-values) option. * **In the JavaScript API, a start state without `opacity: 0` changes the element before it enters.** With `opacity: 0` and a movement, the element waits at its resting position. Other start states wait at the start state. For example, with `{ y: 80 }`, the element waits 80 pixels lower, so [`reveal()` reveals it later](/guides/timing/#the-start-state-moves-the-box-of-reveal). React, Vue and Astro hide a waiting element at its resting position. * **A start state with `blur` [runs on the main thread](/guides/keyframes/#animate-the-properties-that-the-compositor-runs) in Chromium.** The full entrance runs there, not only the blur, so it can stutter when the main thread is busy. On pages that must stay smooth, use a start state without `blur`. # Custom keyframes for scroll animations > Replace the generated entrance with native Web Animations keyframes: set a custom easing, end at the resting style and keep the element's own values. The [`from`](/guides/entrances/) option gives the most common entrances. For full control, give native [Web Animations keyframes](https://developer.mozilla.org/en-US/docs/Web/API/Web_Animations_API/Keyframe_Formats) in the [`keyframes`](/reference/options/#keyframes) option. The keyframes replace the generated entrance. ## Give native keyframes [Section titled “Give native keyframes”](#give-native-keyframes) Set `keyframes` to an array of keyframe objects. This entrance zooms in and bounces a little at the end: You cannot use `from` and `keyframes` together. TypeScript rejects the two options on the same element. ## Set the easing [Section titled “Set the easing”](#set-the-easing) Set the easing in the keyframes. The `easing` of a keyframe applies from that keyframe to the next keyframe. Without an `easing`, the change from a keyframe to the next keyframe is linear. No option sets the easing of the full entrance. The `easing` takes a CSS [easing function](https://developer.mozilla.org/en-US/docs/Web/CSS/Reference/Values/easing-function): * A keyword, such as `ease-out` or `ease-in-out`. * A [`cubic-bezier()`](https://developer.mozilla.org/en-US/docs/Web/CSS/Reference/Values/easing-function/cubic-bezier) curve. A second or fourth number above 1 makes the element go past its end position and come back. * A [`linear()`](https://developer.mozilla.org/en-US/docs/Web/CSS/Reference/Values/easing-function/linear) function. It connects a list of points, so it can make a spring or a bounce. The positions in `linear()` are fractions of the [`duration`](/reference/options/#duration). Set a longer `duration` for a spring with more bounces. It needs Chrome 113, Firefox 112 or Safari 17.2. In other browsers, the element shows with no animation. This example zooms three cards at the same time: with `ease-out`, with a `cubic-bezier()` overshoot and with a `linear()` spring. The curve under each card shows the progress of the entrance over time. The dashed line is the end size. The code shows the `linear()` spring: ## End at the resting style [Section titled “End at the resting style”](#end-at-the-resting-style) The entrance does not keep its last keyframe after it ends. The element then returns to its own style. If the last keyframe is different from that style, the element jumps at the end of the entrance. Make the last keyframe agree with the resting style of the element. ## Keep the element’s own values [Section titled “Keep the element’s own values”](#keep-the-elements-own-values) While the entrance plays, the keyframes replace the element’s own values of the properties that they animate. In the JavaScript API, they also replace them while the element waits. To end at the element’s own value, end with a neutral [additive keyframe](https://developer.mozilla.org/en-US/docs/Web/API/KeyframeEffect/composite). For example, this entrance ends at the `opacity` of the element, also when the CSS sets `opacity: 0.8`: ```js const keyframes = [{ opacity: 0 }, { opacity: 0, composite: "add" }]; ``` An additive keyframe adds its value to the element’s own value. An `opacity` of 0 adds nothing. * A keyframe with `composite` needs Firefox 80 or Safari 16. * Chromium runs an animation with an additive keyframe on the main thread. The animation can stutter when the main thread is busy. ## Give explicit values to the first keyframe [Section titled “Give explicit values to the first keyframe”](#give-explicit-values-to-the-first-keyframe) Set each animated property in the first keyframe. An open WebKit bug ([212409](https://bugs.webkit.org/show_bug.cgi?id=212409)) can take an [implicit start value](https://developer.mozilla.org/en-US/docs/Web/API/Web_Animations_API/Keyframe_Formats#implicit_tofrom_keyframes) from an earlier animation. ## Animate custom properties [Section titled “Animate custom properties”](#animate-custom-properties) A keyframe can animate a CSS [custom property](https://developer.mozilla.org/en-US/docs/Web/CSS/Guides/Cascading_variables/Using_custom_properties), such as `"--progress"`. Register the property with [`@property`](https://developer.mozilla.org/en-US/docs/Web/CSS/Reference/At-rules/@property) and give it a syntax, such as `""`. Without a registration, the browser cannot interpolate the value, so the value changes in one step at the middle of the entrance. ## Animate the properties that the compositor runs [Section titled “Animate the properties that the compositor runs”](#animate-the-properties-that-the-compositor-runs) Animate `opacity`, `transform`, `translate`, `scale` and `rotate` when possible. The browser runs these animations [on the compositor](https://web.dev/articles/stick-to-compositor-only-properties-and-manage-layer-count), so a busy main thread does not make them stutter. A layout property, such as `width`, `top` or `margin`, causes [a layout and a paint](https://web.dev/articles/rendering-performance) on each frame. # Staggered list animations with Cascade > Animate the items of a list, a grid or the words of a heading one after the other with Cascade and the interval option, and reveal long lists item by item. A cascade reveals the children of a container one after the other, when the container enters the viewport. Each package has a cascade API: * React: `Cascade` and `useCascade`. * Vue: `Cascade` and `v-cascade`. * Astro: `Cascade`. * JavaScript: `cascade()`. The cascade APIs accept all the options of a reveal, and also [`interval`](/reference/options/#interval). ## Reveal the items one after the other [Section titled “Reveal the items one after the other”](#reveal-the-items-one-after-the-other) Put the items in a cascade. Select an interval to see the effect: Only the direct element children animate. Text and deeper descendants do not animate. In React, Vue and Astro, a child with [`display: contents`](https://developer.mozilla.org/en-US/docs/Web/CSS/Reference/Properties/display#contents) shows immediately. ## Change the interval [Section titled “Change the interval”](#change-the-interval) `interval` sets the time between the entrances of two children, in milliseconds. The default is 80. The child at position `index` waits `delay + index * interval`. So [`delay`](/guides/timing/#delay-the-entrance) moves the start of the whole sequence. A negative interval gives negative delays. Each later child then starts further into its entrance. ## Reveal the words of a heading [Section titled “Reveal the words of a heading”](#reveal-the-words-of-a-heading) A cascade does not split text. To reveal each word, wrap each word in an element: * React ```jsx import { Cascade } from "@awesome-reveal/react"; export function HeadingWords() { return ( Reveal each word ); } ``` * Vue ```vue ``` * Astro ```astro --- import { Cascade } from "@awesome-reveal/astro"; --- Reveal each word ``` * JavaScript ```js import { cascade } from "@awesome-reveal/core"; cascade("h2.words", { interval: 60 }); ``` The entrance moves the element with a transform, and an [inline element cannot have a transform](https://www.w3.org/TR/css-transforms-1/#transformable-element). So give the words `display: inline-block`. Select `inline` to see the words fade in with no movement: ## Reveal a long list or a tall grid [Section titled “Reveal a long list or a tall grid”](#reveal-a-long-list-or-a-tall-grid) A cascade schedules all its children at the same time. In a long list, or in a grid that is taller than the viewport, the last children start late or out of view. Reveal each item instead: * React ```jsx import { Reveal } from "@awesome-reveal/react"; export function PostList({ posts }) { return (
      {posts.map((post) => ( {post.title} ))}
    ); } ``` * Vue ```vue ``` * Astro ```astro --- import { Reveal } from "@awesome-reveal/astro"; interface Props { posts: { id: string; title: string }[]; } const { posts } = Astro.props; ---
      {posts.map((post) => (
    • {post.title}
    • ))}
    ``` * JavaScript ```js import { reveal } from "@awesome-reveal/core"; reveal("ul.posts > li"); ``` Also reveal each item of a virtualized list. ## Things to know [Section titled “Things to know”](#things-to-know) * **Add the children before the reveal.** In React, Vue and Astro, the cascade reads its children when it reveals. A child that you add after the reveal shows with no animation. For JavaScript, see [Targets](/reference/javascript/#targets). * **Do not put a reveal directly inside a cascade.** In React and Vue, the two entrances combine on the same element. In Astro, the host of a nested `Reveal` has `display: contents`, so the cascade does not animate it, and the nested `Reveal` plays only its own entrance. * **Wrap an Astro island in an element.** An [island](https://docs.astro.build/en/concepts/islands/) has `display: contents`, so the cascade does not animate it. * **A Vue [``](https://vuejs.org/guide/built-ins/transition-group.html) adds its own animations.** As a direct child of a cascade, it animates the children too. * **A React fragment gives one child for each element.** A component that returns a [fragment](https://react.dev/reference/react/Fragment) gives one cascade child for each element of the fragment. * **The reveal event comes from the container.** [`onReveal` and the `reveal` event](/guides/reveal-events/#run-code-when-the-reveal-starts) get the container, not each child. # Trigger reveal animations manually > Play a reveal animation from your own state with the when option, replay it, hide content with hidden, and play the entrance of clipped content by hand. By default, the viewport controls the entrance. The [`when`](/reference/options/#when) option of React, Vue and Astro gives the control to your own state. `@awesome-reveal/core` does not have `when`. ## Reveal from your state [Section titled “Reveal from your state”](#reveal-from-your-state) Set `when` to `true` to reveal the element, and to `false` to reset the entrance. A reset has no exit animation. With no value or `null`, the viewport controls the entrance. A change from `true` to `null` keeps the element revealed. In this example, a button shows and hides the details: In Astro, the `when` prop sets the value in the server HTML. In a client script, pass the rendered tag to [`getReveal`](/reference/astro/#getreveal), and set the `when` property of the result. A change to `when` applies immediately. If `when` becomes `false` during the [`delay`](/guides/timing/#delay-the-entrance), the entrance resets and does not play. ## Play the entrance again [Section titled “Play the entrance again”](#play-the-entrance-again) The entrance plays one time. To play it again, set `when` to `false`, then to `true`. ## Hide the content [Section titled “Hide the content”](#hide-the-content) `when` does not show or hide content. With `false`, the element is transparent, but screen readers read it, and the keyboard can focus its controls. To hide content, also set [`hidden`](https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Global_attributes/hidden), or do not render it. The example above sets `hidden`. [`inert`](https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Global_attributes/inert) does not hide content. It only blocks focus, clicks and assistive technology. Reduced motion has priority over `when`. If the user asks for [reduced motion](https://developer.mozilla.org/en-US/docs/Web/CSS/Reference/At-rules/@media/prefers-reduced-motion), the element reveals, also when `when` is `false`. For focus in an element with `when` set to `false`, see [Accessibility](/concepts/accessibility/#focus). ## Play clipped content by hand [Section titled “Play clipped content by hand”](#play-clipped-content-by-hand) If an ancestor with `overflow` clips the element fully, the element does not reveal. An example is a carousel slide that its track clips. In React, Vue and Astro, set `when` to `true` when the slide becomes visible. `@awesome-reveal/core` has no manual trigger. To play a waiting entrance, play the paused animations of the element: ```js import { reveal } from "@awesome-reveal/core"; reveal(".slide", { from: "left" }); export function playEntrance(slide) { for (const animation of slide.getAnimations()) { if (animation.playState === "paused") animation.play(); } } ``` For a cascade, call [`getAnimations({ subtree: true })`](https://developer.mozilla.org/en-US/docs/Web/API/Element/getAnimations) on the container. The loop also plays your own paused animations of the element. # Migrate from react-awesome-reveal v4 > Move from react-awesome-reveal v4 to @awesome-reveal/react: replace Fade, Slide, Zoom and the other effect components, and update renamed and removed props. Version 5 of `react-awesome-reveal` changes the API on purpose. It replaces the effect components and Emotion with the `Reveal` and `Cascade` components and native [Web Animations](https://developer.mozilla.org/en-US/docs/Web/API/Web_Animations_API). Do the steps on this page to migrate your code. ## Choose the package [Section titled “Choose the package”](#choose-the-package) You can use one of these packages. The two packages give the same API. * **`@awesome-reveal/react`.** Use it for a new project, and to get all future versions. * **`react-awesome-reveal` v5.** It re-exports `@awesome-reveal/react`, so you can keep the `react-awesome-reveal` import path. ```sh pnpm add @awesome-reveal/react # or, to keep the import path: pnpm add react-awesome-reveal ``` ## Check the requirements [Section titled “Check the requirements”](#check-the-requirements) * React 18 or 19. * A bundler or a runtime that loads ES modules. The packages are ES modules only. * If no other code uses Emotion, remove it. Version 5 does not use Emotion. ## Replace the effect components [Section titled “Replace the effect components”](#replace-the-effect-components) `Reveal` is a named export. Version 4 also had a default export. ```jsx import { Reveal } from "@awesome-reveal/react"; ``` Replace each effect component with `Reveal`, and set [`from`](/guides/entrances/). `from` names the side where the element starts. In v4, `left` and `right` also name that side, but `up` and `down` name the movement. So `up` becomes a start on the bottom side. A side in `from` moves the element 24 pixels. The v4 effects moved it by its full size, so this table gives the v4 start position. To use the shorter v5 motion, set `from` to the side, for example `from="bottom"`. The generated entrance has a different easing and duration than v4. To keep the v4 duration, set `duration={1000}`. | v4 | `from` with the v4 start position | | --------------------------------------- | ---------------------------------------- | | `` | `{ opacity: 0 }` | | `` | `{ opacity: 0, y: "100%" }` | | `` | `{ opacity: 0, y: "-100%" }` | | `` | `{ opacity: 0, x: "-100%" }` | | `` | `{ opacity: 0, x: "100%" }` | | `` | `{ opacity: 0, x: "-100%", y: "-100%" }` | | `` | `{ opacity: 0, x: "100%", y: "-100%" }` | | `` | `{ opacity: 0, x: "-100%", y: "100%" }` | | `` | `{ opacity: 0, x: "100%", y: "100%" }` | | `` | `{ opacity: 0, y: 2000 }` | | `` or `` | `{ x: "-100%" }` | | `` | `{ x: "100%" }` | | `` | `{ y: "100%" }` | | `` | `{ y: "-100%" }` | | `` | `{ opacity: 0, scale: 0.3 }` | | `` | `{ opacity: 0, rotate: -200 }` | | A `` with no `keyframes` | `{ opacity: 0, x: "-100%" }` | The `big` prop with `down`, `left` or `right` also moves the element 2000 pixels, on the applicable axis. For `Bounce`, `Flip`, `Hinge`, `JackInTheBox`, `Roll` and `AttentionSeeker`, and for `Zoom` or `Rotate` with a direction, use native keyframes. See the next section. ## Change Emotion keyframes into native keyframes [Section titled “Change Emotion keyframes into native keyframes”](#change-emotion-keyframes-into-native-keyframes) Version 4 took Emotion `keyframes`. Version 5 takes an array of native [keyframe objects](https://developer.mozilla.org/en-US/docs/Web/API/Web_Animations_API/Keyframe_Formats). Change each step of the CSS animation into an object: * Put the percentage of the step in `offset`, from 0 to 1. * Put the [`animation-timing-function`](https://developer.mozilla.org/en-US/docs/Web/CSS/Reference/Properties/animation-timing-function) of the step in `easing`. v4 used `ease` for each step with no timing function of its own. A keyframe with no `easing` is linear. * Make the last keyframe agree with the resting style of the element. ```jsx import { Reveal } from "@awesome-reveal/react"; Zoom in ; ``` These keyframes give the exact v4 `Zoom` entrance, which reaches full opacity at the middle. The `from` value in the table above fades over the full entrance. See [Use your own keyframes](/guides/keyframes/). ## Update the props [Section titled “Update the props”](#update-the-props) | v4 | v5 | | ------------------------------ | ---------------------------------------------------------------------------------------------------------------------- | | `cascade` | The `Cascade` component. For a list, render the list with `Cascade`, for example ``. | | `damping` | [`interval`](/guides/lists/#change-the-interval) on `Cascade`. Set it to the v4 `duration * damping`, in milliseconds. | | `duration` | `duration`. The default is 600 milliseconds. The v4 default was 1000. | | `delay` | `delay`, in milliseconds. In a cascade, it moves the start of the whole sequence. | | `fraction` | [`threshold`](/guides/timing/#reveal-later-with-a-threshold). | | `triggerOnce` | Remove it. The entrance plays one time. To play it again, set `when` to `false`, then to `true`. | | `direction`, `big` | `from`. See the table above. | | `keyframes` | `keyframes`, with native keyframes. | | `className`, `style` | They apply to the one element that `Reveal` renders. | | `childClassName`, `childStyle` | Style the children directly. | | `onVisibilityChange` | [`onReveal`](/guides/reveal-events/). It gets the element, one time for each reveal. | | `reverse` | No replacement. Version 5 has no exit animations. | This example shows a v4 cascade and its v5 version: v4 ```jsx import { Fade } from "react-awesome-reveal";

    One

    Two

    ; ``` v5 ```jsx import { Cascade } from "@awesome-reveal/react";

    One

    Two

    ; ``` ## Behavior changes [Section titled “Behavior changes”](#behavior-changes) The type check does not find these changes. Check them after the migration: * **One element.** `Reveal` renders one element around its children, and `as` sets its tag. Version 4 wrapped each element child in a `div`, and animated each `li` of a list child. * **One observer.** One observer watches the whole `Reveal`, so all its children reveal together. For a long list, use one `Reveal` for each item. * **`Cascade` does not split text.** To reveal each word, wrap each word in an element. See [Animate a list](/guides/lists/#reveal-the-words-of-a-heading). * **A new easing.** The generated entrance uses `cubic-bezier(0.22, 1, 0.36, 1)`. To change it, use native keyframes. * **One play.** The entrance plays one time. In v4, it played each time by default. Also check the refs, the hydration, reduced motion and the teardown. ## Set up the stylesheet [Section titled “Set up the stylesheet”](#set-up-the-stylesheet) The package loads its stylesheet automatically. Two setups need a step: * **Next.js Pages Router with webpack.** Add `@awesome-reveal/react` to [`transpilePackages`](https://nextjs.org/docs/pages/api-reference/config/next-config-js/transpilePackages). Add it also when you install only `react-awesome-reveal`. next.config.mjs ```js export default { transpilePackages: ["@awesome-reveal/react"] }; ``` * **Astro island.** Import `reveal.css` in the page or the layout, from the package that you install: `react-awesome-reveal/reveal.css` or `@awesome-reveal/react/reveal.css`. The Next.js App Router and Turbopack need no step. ## Migrate with an agent [Section titled “Migrate with an agent”](#migrate-with-an-agent) The `migrating-from-v4` skill teaches a coding agent all the changes from v4. To get it, see [Agent skills](/guides/ai-agents/#agent-skills). # Run code when an element reveals > Run code when an element scrolls into view with onReveal, the Vue reveal event or the Astro reveal DOM event, and wait for the end of the entrance animation. React, Vue and Astro tell your code when an element reveals. `@awesome-reveal/core` has no callback. ## Run code when the reveal starts [Section titled “Run code when the reveal starts”](#run-code-when-the-reveal-starts) Each package gives the revealed element in a different way: * React: the [`onReveal`](/reference/options/#onreveal) prop. * Vue: the `reveal` event of `Reveal` and `Cascade`, and the `onReveal` option of `v-reveal` and `v-cascade`. * Astro: the [`reveal` DOM event](/reference/astro/#the-reveal-event). The example logs the reveal event and the end of the entrance. Select Replay to see the events again. The code runs one time for each reveal, when the reveal starts. In a cascade, it gets the container. * It also runs when no entrance plays, for example with [reduced motion](https://developer.mozilla.org/en-US/docs/Web/CSS/Reference/At-rules/@media/prefers-reduced-motion), or when focus shows a waiting element. * In React, it runs one time also in [StrictMode](https://react.dev/reference/react/StrictMode). * After [`when`](/guides/manual-control/#reveal-from-your-state) becomes `false`, the next reveal runs it again. With reduced motion, the element does not reset, so the code does not run again. ## Wait for the end of the entrance [Section titled “Wait for the end of the entrance”](#wait-for-the-end-of-the-entrance) The entrance is a set of [Web Animations](https://developer.mozilla.org/en-US/docs/Web/API/Web_Animations_API) on the element. To wait for its end, wait for the [`finished`](https://developer.mozilla.org/en-US/docs/Web/API/Animation/finished) promises of these animations: ```js function entranceFinished(element) { return Promise.all( element.getAnimations().map((animation) => animation.finished), ); } // In the reveal callback: entranceFinished(element) .then(() => element.classList.add("entered")) .catch(() => {}); ``` * The promise rejects when the entrance stops early, for example after `when` becomes `false` or an unmount. Catch the rejection. * The promise resolves immediately when no entrance plays, for example with reduced motion. * The promise also waits for your own animations of the element. An animation that repeats forever never finishes, so the promise does not resolve. For a cascade, call [`getAnimations({ subtree: true })`](https://developer.mozilla.org/en-US/docs/Web/API/Element/getAnimations) on the container, because the children animate. The promise then also waits for the animations of all the descendants. In the JavaScript API, a waiting entrance is a paused animation, and a paused animation does not finish. If your code waits for all of [`document.getAnimations()`](https://developer.mozilla.org/en-US/docs/Web/API/Document/getAnimations), skip the animations with `playState === "paused"`. ## Read the revealed state [Section titled “Read the revealed state”](#read-the-revealed-state) React and Vue give a `revealed` value that is `true` after the reveal. In Astro, the result of [`getReveal`](/reference/astro/#getreveal) has a `revealed` property. * React ```jsx import { useReveal } from "@awesome-reveal/react"; export function RevealedCard() { const { getProps, revealed } = useReveal(); return
    {revealed ? "Hello" : "Waiting"}
    ; } ``` * Vue ```vue ``` * Astro ```astro --- import { Reveal } from "@awesome-reveal/astro"; --- Hello ``` In React, `useReveal` animates your own element with no wrapper. Spread `getProps()` on one DOM element. # Animation duration, delay and threshold > Change the duration and the delay of a scroll reveal animation, and set the visible fraction of the element that starts it with the threshold option. Three options set when the entrance plays and how long it takes: [`duration`](/reference/options/#duration), [`delay`](/reference/options/#delay) and [`threshold`](/reference/options/#threshold). ## Change the duration [Section titled “Change the duration”](#change-the-duration) `duration` sets the duration of the entrance, in milliseconds. The default is 600. Select a duration to see the effect: ## Delay the entrance [Section titled “Delay the entrance”](#delay-the-entrance) `delay` sets the time between the reveal and the start of the entrance, in milliseconds. The default is 0. The element keeps its start state during the delay. In this example, the title takes 800 milliseconds. The text starts 200 milliseconds after its reveal, so it starts while the title still moves: Keep `delay` below about 300 milliseconds. A long delay makes content appear late when the user scrolls quickly. ## Reveal later with a threshold [Section titled “Reveal later with a threshold”](#reveal-later-with-a-threshold) `threshold` sets the [visible fraction](https://developer.mozilla.org/en-US/docs/Web/API/Intersection_Observer_API#thresholds) of the element that reveals it, from 0 to 1. The default is 0, so the element reveals when its first pixel enters the viewport. With 0.5, the element reveals when half of it is visible: * React ```jsx import { Reveal } from "@awesome-reveal/react"; export function DownloadsChart() { return ( Downloads for each month ); } ``` * Vue ```vue ``` * Astro ```astro --- import { Reveal } from "@awesome-reveal/astro"; --- Downloads for each month ``` * JavaScript ```js import { reveal } from "@awesome-reveal/core"; reveal(".chart", { threshold: 0.5 }); ``` A change to `threshold` applies immediately in React, Vue and Astro. A change to `duration` or `delay` applies at the next reveal. ### Tall elements and small scroll containers [Section titled “Tall elements and small scroll containers”](#tall-elements-and-small-scroll-containers) * If the viewport is too small to show the threshold fraction of the element, the element reveals when it enters the viewport. * In a [scroll container](https://developer.mozilla.org/en-US/docs/Glossary/Scroll_container) that is too small, the element reveals when it leaves the visible area of the container. Keep the default threshold for tall elements and for [long cascades](/guides/lists/#reveal-a-long-list-or-a-tall-grid). ### The start state moves the box of `reveal()` [Section titled “The start state moves the box of reveal()”](#the-start-state-moves-the-box-of-reveal) React, Vue and Astro hide a waiting element with CSS at its resting position. They create the entrance at the reveal, so the start state does not change the box that the viewport check uses. `reveal()` of the JavaScript API holds a waiting element at the first keyframe of a paused entrance. A [start state](/guides/entrances/) with `opacity: 0`, such as each side, waits at the resting position of the element. Other start states and [your own keyframes](/guides/keyframes/) wait at their first keyframe. Their offset, scale and rotation change the box that the viewport check uses. For example, with the start state `{ y: 80 }`, the element waits 80 pixels lower, so it reveals later. `cascade()` holds each child at its first keyframe, but the viewport check uses the box of the container. So the start state of the children does not change when the cascade reveals. # Troubleshoot scroll reveal animations > Fix common Awesome Reveal problems: content that never shows, shows early, hides again or has no animation, elements that lose their styles, and console errors. 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”](#the-content-never-shows) * **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](/guides/manual-control/#play-clipped-content-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()`](/guides/timing/#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](/guides/manual-control/#reveal-from-your-state). If no script attaches the element, the content shows after 5 seconds. See [The 5 second hold](/concepts/server-rendering/#the-5-second-hold). ## The content reveals too late or too early [Section titled “The content reveals too late or too early”](#the-content-reveals-too-late-or-too-early) * **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()`](/guides/timing/#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](/guides/lists/#reveal-a-long-list-or-a-tall-grid). * **The `delay` is long.** Keep it short. See [Delay the entrance](/guides/timing/#delay-the-entrance). ## The content shows, then hides again [Section titled “The content shows, then hides again”](#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](/concepts/server-rendering/#the-5-second-hold). Hydrate the reveal content eagerly: * **React or Vue in an Astro island:** use [`client:load`](/frameworks/react-vue-astro/#hydrate-the-island-with-clientload), not `client:visible`. * **Vue and Nuxt:** do not use [lazy hydration](/frameworks/vue-ssr-nuxt/#hydrate-the-reveals-eagerly) 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-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](/concepts/server-rendering/#the-javascript-api). * **The page does not load the stylesheet.** Some setups need a step. See [Hidden in the server HTML](/concepts/server-rendering/#hidden-in-the-server-html). * **A Content Security Policy blocks the stylesheet in Astro.** See [Content Security Policy](/frameworks/astro/#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](/concepts/server-rendering/#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](/concepts/server-rendering/#when-the-stylesheet-does-not-hide-content). ## The content shows with no animation [Section titled “The content shows with no animation”](#the-content-shows-with-no-animation) * **The user asks for reduced motion.** See [Reduced motion](/concepts/accessibility/#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](/concepts/accessibility/#focus). * **The browser rejected an option.** An invalid easing or duration shows the element with no animation. See [Errors](/concepts/how-it-works/#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](/guides/lists/#things-to-know). In the JavaScript API, a child that you add after the `cascade()` call shows with no animation. See [Targets](/reference/javascript/#targets). * **In Astro, the HTML parser moved the element.** See [Where to place a reveal](/frameworks/astro/#where-to-place-a-reveal). * **The browser is too old.** See [Older browsers](/reference/browser-support/#older-browsers). ## The element loses its own styles [Section titled “The element loses its own styles”](#the-element-loses-its-own-styles) * **The entrance replaces the element’s own values of the animated properties.** An example is a `rotate` or an `opacity` that your CSS sets. [Put the value on an inner element](/guides/entrances/#things-to-know), or [use an additive keyframe](/guides/keyframes/#keep-the-elements-own-values). * **In React, Vue and Astro, the stylesheet replaces your own `animation` until the reveal.** Put your animation on an inner element. See [Things to know](/concepts/server-rendering/#things-to-know). * **Two calls reveal the same element.** The later entrance replaces the earlier entrance. See [Do not reveal one element two times](/concepts/how-it-works/#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-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](/guides/keyframes/#end-at-the-resting-style). ## Your code waits for animations that never finish [Section titled “Your code waits for animations that never finish”](#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](/guides/reveal-events/#wait-for-the-end-of-the-entrance). ## The build fails [Section titled “The build fails”](#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](/frameworks/nextjs/#set-up-the-pages-router-with-webpack). ## Errors in the console [Section titled “Errors in the console”](#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](/concepts/how-it-works/#errors). * **An invalid CSS selector.** `reveal()` and `cascade()` throw a `SyntaxError`. See [Errors](/concepts/how-it-works/#errors). * **`The HTML parser moved the element out of `.** In Astro, the reveal is in a place that the HTML parser does not accept. See [Where to place a reveal](/frameworks/astro/#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`](/reference/astro/#getreveal). ## Get help [Section titled “Get help”](#get-help) If this page does not solve your problem, search the [issues](https://github.com/awesome-reveal/awesome-reveal/issues) of the packages repo. To ask a question, open a [discussion](https://github.com/awesome-reveal/awesome-reveal/discussions). To report a bug, open an issue with a minimal example. # Astro reveal API: Reveal and Cascade > API reference of @awesome-reveal/astro: the Reveal and Cascade components, the getReveal function for client scripts, the reveal event and the RevealTag type. `@awesome-reveal/astro` exports two components and the [`getReveal`](#getreveal) function. The components take the same [options](/reference/options/) as props. For the supported versions, see [Requirements](/getting-started/#requirements). ```js import { Cascade, getReveal, Reveal } from "@awesome-reveal/astro"; ``` ## Reveal [Section titled “Reveal”](#reveal) Renders a tag around its children, and reveals the tag when it enters the viewport. ```astro Hello ``` * **Props**: `as`, `from`, `keyframes`, `duration`, `delay`, `threshold` and `when`. See [Options](/reference/options/). * **Other attributes**: the component gives them to the rendered tag, for example `class` and `id`. * **`as`**: a [`RevealTag`](#types). The default is `"div"`. The props go into the server HTML, so they must be values that JSON can serialize. To run code at the reveal, listen to the [`reveal` event](#the-reveal-event). ## Cascade [Section titled “Cascade”](#cascade) Renders a tag around its children. When the tag enters the viewport, it reveals the direct element children one after the other. See [Animate a list](/guides/lists/). `Cascade` accepts the props of `Reveal`, and [`interval`](/reference/options/#interval). ## getReveal [Section titled “getReveal”](#getreveal) Gives the control of the reveal of a tag that `Reveal` or `Cascade` rendered. Call it in a [processed ` ``` * **Argument**: the rendered tag, for example the element with the `id` of the component. * **Return value**: a `RevealControl` object with the members in the table below. * **Errors**: `getReveal` throws an `Error` for any other element. The HTML parser can move the tag out of its place, for example out of a `

    `. See [Where to place a reveal](/frameworks/astro/#where-to-place-a-reveal). * **Navigations**: with the ``, call `getReveal` again after each navigation, because the new page has new elements. See [View transitions](/frameworks/astro/#view-transitions). | Member | Type | Description | | ---------- | ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------- | | `when` | `boolean \| null` | Gets or sets the [manual control](/guides/manual-control/). `null` gives the control to the viewport and keeps a revealed element revealed. | | `revealed` | `boolean` | `true` after the reveal. Read only. It is `false` until the client script attaches the element. | ## The reveal event [Section titled “The reveal event”](#the-reveal-event) The rendered tag dispatches a `reveal` event when the reveal starts. The event [bubbles](https://developer.mozilla.org/en-US/docs/Web/API/Event/bubbles), so you can listen on an ancestor or on `document`. See [Run code when the reveal starts](/guides/reveal-events/#run-code-when-the-reveal-starts). ## Types [Section titled “Types”](#types) | Type | Description | | ---------------- | --------------------------------------------------------------- | | `RevealProps` | The props of `Reveal`. | | `CascadeProps` | The props of `Cascade`. | | `RevealTag` | The tags that `as` accepts. See [`as`](/reference/options/#as). | | `RevealControl` | The object that [`getReveal`](#getreveal) returns. | | `RevealOptions` | The reveal options. | | `CascadeOptions` | The cascade options. | | `Side` | The sides of [`from`](/reference/options/#from). | | `StartState` | The [start state](/guides/entrances/) object of `from`. | # Browser support for scroll animations > The browsers that Awesome Reveal supports, the browser features with other minimum versions, and what happens in older browsers without the required APIs. The two browser APIs that [Awesome Reveal uses](/concepts/how-it-works/) are [Baseline Widely available](https://developer.mozilla.org/en-US/docs/Glossary/Baseline/Compatibility). For the Node.js and framework versions, see [Requirements](/getting-started/#requirements). ## Browsers [Section titled “Browsers”](#browsers) All packages support these browsers, or later versions: | Browser | Version | | ------------- | ------- | | Chrome | 104 | | Edge | 104 | | Firefox | 74 | | Safari | 14.1 | | Safari on iOS | 14.5 | ## Features with other versions [Section titled “Features with other versions”](#features-with-other-versions) Some features need a later version, or are not available in all supported browsers: * **Keyframes with `composite`**: see [Keep the element’s own values](/guides/keyframes/#keep-the-elements-own-values). * **`linear()` easing**: see [Set the easing](/guides/keyframes/#set-the-easing). * **Keyframes with implicit start values**: see [Give explicit values to the first keyframe](/guides/keyframes/#give-explicit-values-to-the-first-keyframe). * **The `scripting` media feature**: see [When the stylesheet does not hide content](/concepts/server-rendering/#when-the-stylesheet-does-not-hide-content). ## Older browsers [Section titled “Older browsers”](#older-browsers) In a browser without one of the two APIs, the content does not stay hidden: * Without the Intersection Observer API, the entrance plays immediately. * Without [`Element.animate()`](https://developer.mozilla.org/en-US/docs/Web/API/Element/animate), the content shows with no animation. The packages need no polyfill. # JavaScript scroll reveal API > API reference of @awesome-reveal/core: the reveal and cascade functions, the targets that they accept, the RevealHandle with dispose, and the exported types. `@awesome-reveal/core` exports two functions. They work with no framework, and they need no stylesheet. ```js import { cascade, reveal } from "@awesome-reveal/core"; ``` For server rendering, see [The JavaScript API](/concepts/server-rendering/#the-javascript-api). ## reveal() [Section titled “reveal()”](#reveal) ```ts reveal(target: RevealTarget, options?: RevealOptions): RevealHandle ``` Reveals each [target](#targets) when it enters the viewport. * **`options`**: `from`, `keyframes`, `duration`, `delay` and `threshold`. See [Options](/reference/options/). * **Return value**: a [`RevealHandle`](#revealhandle). ## cascade() [Section titled “cascade()”](#cascade) ```ts cascade(target: RevealTarget, options?: CascadeOptions): RevealHandle ``` Reveals the direct element children of each [target](#targets), one after the other, when the target enters the viewport. See [Animate a list](/guides/lists/). * **`options`**: the options of `reveal()`, and [`interval`](/reference/options/#interval). * **Return value**: a [`RevealHandle`](#revealhandle). ## Targets [Section titled “Targets”](#targets) `target` is one of these values: * an element * a CSS selector, such as `".card"` * an iterable of elements, such as an array or a `NodeList` * an array-like collection, such as `element.children` The function finds the targets, and the children of a cascade, one time, when you call it. It does not see elements that you add later. Call it again for new elements. For a selector that is not valid, see [Errors](/concepts/how-it-works/#errors). ## RevealHandle [Section titled “RevealHandle”](#revealhandle) The return value of `reveal()` and `cascade()`. It has one method. ### dispose() [Section titled “dispose()”](#dispose) Stops the observation and the animations of the call. Each element returns to its resting style. Call it when you remove the elements, for example when your component unmounts. A finished entrance needs no `dispose()`. See [One entrance for each element](/concepts/how-it-works/#one-entrance-for-each-element). ## Types [Section titled “Types”](#types) | Type | Description | | ---------------- | ------------------------------------------------------- | | `RevealOptions` | The options of `reveal()`. | | `CascadeOptions` | The options of `cascade()`. | | `RevealTarget` | The [targets](#targets) that the functions accept. | | `RevealHandle` | The return value of the functions. | | `Side` | The sides of [`from`](/reference/options/#from). | | `StartState` | The [start state](/guides/entrances/) object of `from`. | # Reveal animation options reference > The reveal options of Awesome Reveal, with types and default values. from, keyframes, duration, delay, threshold, interval, when, onReveal and as. All packages use the same options, with the same default values. In React, Vue and Astro, an option is a prop of `Reveal` and `Cascade`. Some options are not available in all APIs. See [Where you can use each option](#where-you-can-use-each-option). The React hooks, the Vue directives and the core functions take the options as an object. ## Summary [Section titled “Summary”](#summary) | Option | Type | Default | | ------------------------- | ---------------------------- | ---------- | | [`from`](#from) | `Side \| StartState` | `"bottom"` | | [`keyframes`](#keyframes) | `Keyframe[]` | | | [`duration`](#duration) | `number` | `600` | | [`delay`](#delay) | `number` | `0` | | [`threshold`](#threshold) | `number` | `0` | | [`interval`](#interval) | `number` | `80` | | [`when`](#when) | `boolean \| null` | | | [`onReveal`](#onreveal) | `(element: Element) => void` | | | [`as`](#as) | tag name | `"div"` | ## Where you can use each option [Section titled “Where you can use each option”](#where-you-can-use-each-option) * `from`, `keyframes`, `duration`, `delay` and `threshold` work with all APIs. * `interval` works with the cascade APIs: * React: `Cascade` and `useCascade`. * Vue: `Cascade` and `v-cascade`. * Astro: `Cascade`. * JavaScript: `cascade()`. * `when` works with all APIs of React, Vue and Astro. JavaScript does not have it. * `onReveal` has these limits: * React: all APIs. * Vue: `v-reveal` and `v-cascade`. The components emit a `reveal` event. * Astro: not available. Listen to `reveal` events. * JavaScript: not available. * `as` works with `Reveal` and `Cascade` in React, Vue and Astro. ## Entrance options [Section titled “Entrance options”](#entrance-options) ### from [Section titled “from”](#from) **Type:** `"top" | "right" | "bottom" | "left" | StartState`. **Default:** `"bottom"`. Sets the start state of the entrance. A side gives a fade and a movement of 24 pixels from that side. A `StartState` object sets the complete start state, with the properties `opacity`, `x`, `y`, `scale`, `rotate` and `blur`. A number is in pixels for `x`, `y` and `blur`, and in degrees for `rotate`. A string contains a CSS value with its unit. You cannot use `from` and `keyframes` together. See [Choose the entrance](/guides/entrances/). ### keyframes [Section titled “keyframes”](#keyframes) **Type:** `Keyframe[]`. **No default.** Replaces the generated entrance with native [Web Animations keyframes](https://developer.mozilla.org/en-US/docs/Web/API/Web_Animations_API/Keyframe_Formats). Use it for a [different easing](/guides/keyframes/#set-the-easing) or for properties that `from` does not animate. * End the keyframes at the resting style of the element. The entrance does not keep its last keyframe. * Give explicit values to the first keyframe. * Set the easing in the keyframes. No option sets the easing. ### duration [Section titled “duration”](#duration) **Type:** `number`. **Default:** `600`. The duration of the entrance, in milliseconds. ### delay [Section titled “delay”](#delay) **Type:** `number`. **Default:** `0`. The time between the reveal and the start of the entrance, in milliseconds. The element keeps its start state during the delay. Keep `delay` below about 300 milliseconds. A long delay makes content appear late when the user scrolls quickly. ## Viewport options [Section titled “Viewport options”](#viewport-options) ### threshold [Section titled “threshold”](#threshold) **Type:** `number`, from `0` to `1`. **Default:** `0`. The [visible fraction](/guides/timing/#reveal-later-with-a-threshold) of the element that reveals it. With `0`, the element reveals when its first pixel enters the viewport. With `0.5`, it reveals when half of it is visible. If the viewport is too small to show this fraction of the element, the element reveals when it enters the viewport. Keep the default for tall elements and long cascades. ## Cascade options [Section titled “Cascade options”](#cascade-options) ### interval [Section titled “interval”](#interval) **Type:** `number`. **Default:** `80`. The time between the entrances of two [direct element children](/guides/lists/#reveal-the-items-one-after-the-other), in milliseconds. The child at position `index` waits `delay + index * interval`. A negative value starts each later child further into its entrance. Only `Cascade`, `useCascade`, `v-cascade` and `cascade()` accept `interval`. ## Control options [Section titled “Control options”](#control-options) `@awesome-reveal/core` does not have these options. Astro does not have `onReveal`, and in Vue only the directives accept it. ### when [Section titled “when”](#when) **Type:** `boolean | null`. **No default.** Controls the entrance [manually](/guides/manual-control/). `true` reveals the element, and `false` resets the entrance, with no exit animation. With no value or `null`, the viewport controls the entrance. A change from `true` to `null` keeps the element revealed. To play the entrance again, set `when` to `false`, then to `true`. `when` does not show or hide content. With `false`, the element is transparent, but screen readers read it and the keyboard can focus its controls. To hide content, also set [`hidden`](https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Global_attributes/hidden), or do not render it. If the user asks for [reduced motion](https://developer.mozilla.org/en-US/docs/Web/CSS/Reference/At-rules/@media/prefers-reduced-motion), the element reveals also when `when` is `false`. In Astro, to change `when` in a client script, use [`getReveal`](/reference/astro/#getreveal). ### onReveal [Section titled “onReveal”](#onreveal) **Type:** `(element: Element) => void`. **No default.** Runs [one time for each reveal](/guides/reveal-events/), when the reveal starts. It also runs when no entrance plays, for example with reduced motion. It gets the revealed element. * In Vue, the `Reveal` and `Cascade` components emit a `reveal` event. The `v-reveal` and `v-cascade` directives accept `onReveal`. * In Astro, the rendered tag dispatches a `reveal` event that bubbles. ## Component props [Section titled “Component props”](#component-props) ### as [Section titled “as”](#as) **Type:** a tag name. **Default:** `"div"`. Sets the tag that `Reveal` and `Cascade` render, for example `"section"` or `"ul"`. The other attributes of the component go to this tag. In Astro, `as` cannot be a document tag (`html`, `head` or `body`), a table part (such as `tr` or `td`) or a tag that exists only in SVG. The HTML parser moves these tags out of the [custom element](https://developer.mozilla.org/en-US/docs/Web/API/Web_components/Using_custom_elements). # React reveal API: components and hooks > API reference of @awesome-reveal/react: the Reveal and Cascade components, the useReveal and useCascade hooks, getProps, and the exported TypeScript types. `@awesome-reveal/react` exports two components and two hooks. They take the same [options](/reference/options/), as props or as an object. For the supported versions, see [Requirements](/getting-started/#requirements). ```js import { Cascade, Reveal, useCascade, useReveal } from "@awesome-reveal/react"; ``` ## Reveal [Section titled “Reveal”](#reveal) Renders an element around its children, and reveals the element when it enters the viewport. ```tsx Hello ``` * **Props**: `as`, `from`, `keyframes`, `duration`, `delay`, `threshold`, `when` and `onReveal`. See [Options](/reference/options/). * **Other props**: the component gives them to the rendered element, for example `className`, `id` and `ref`. * **`as`**: an HTML or SVG tag. The types of the other props and of `ref` follow the tag. ## Cascade [Section titled “Cascade”](#cascade) Renders an element around its children. When the element enters the viewport, it reveals the direct element children one after the other. See [Animate a list](/guides/lists/). `Cascade` accepts the props of `Reveal`, and [`interval`](/reference/options/#interval). ## useReveal [Section titled “useReveal”](#usereveal) Reveals an element that you render, with no wrapper element. ```tsx import { useReveal } from "@awesome-reveal/react"; export function Card() { const { getProps, revealed } = useReveal({ from: "left" }); return (

    {revealed ? "Hello" : "Waiting"}
    ); } ``` * **Parameter**: the options of `Reveal`, except `as`. * **Type parameter**: the type of the element. The default is `HTMLElement`. * **Return value**: a [`RevealState`](#revealstate). ## useCascade [Section titled “useCascade”](#usecascade) Reveals the direct element children of an element that you render. It accepts the options of `useReveal`, and [`interval`](/reference/options/#interval). It returns a [`RevealState`](#revealstate). ## RevealState [Section titled “RevealState”](#revealstate) The hooks return an object with two members. ### getProps [Section titled “getProps”](#getprops) ```ts getProps

    ( props?: P & { ref?: Ref }, ): Omit & RevealTargetProps ``` Adds the reveal to the props of your element. Spread the result on one DOM element. `getProps()` returns your props with two changes: * **`ref`**: a ref callback. If you give your own `ref`, `getProps()` merges it. Your ref can be an object or a callback. In React 19, a callback can return a cleanup function. * **`data-awesome-reveal`**: the attribute that the [package stylesheet](/concepts/server-rendering/) hides. It has no value after the reveal. For your own component, give the `ref` and the `data-awesome-reveal` prop to a DOM element. ### revealed [Section titled “revealed”](#revealed) **Type:** `boolean`. `true` after the reveal. It is `false` in the server render. See [Read the revealed state](/guides/reveal-events/#read-the-revealed-state). ## Server Components [Section titled “Server Components”](#server-components) To use `Reveal`, `Cascade` and the hooks with Server Components, see [Next.js](/frameworks/nextjs/). ## Stylesheet [Section titled “Stylesheet”](#stylesheet) The package imports its stylesheet. It also exports the stylesheet as `@awesome-reveal/react/reveal.css`, for the [setups that need an import](/concepts/server-rendering/#hidden-in-the-server-html). ## Types [Section titled “Types”](#types) | Type | Description | | ---------------------- | ------------------------------------------------------------------ | | `RevealProps` | The props of `Reveal`. `T` is the tag, and the default is `"div"`. | | `CascadeProps` | The props of `Cascade`. | | `RevealOptions` | The options of `useReveal`. | | `CascadeOptions` | The options of `useCascade`. | | `RevealState` | The return value of the hooks. `T` is the type of the element. | | `RevealTargetProps` | The props that `getProps()` adds: `ref` and `data-awesome-reveal`. | | `Side` | The sides of [`from`](/reference/options/#from). | | `StartState` | The [start state](/guides/entrances/) object of `from`. | # Vue reveal API: components and directives > API reference of @awesome-reveal/vue: the Reveal and Cascade components, the v-reveal and v-cascade directives, the reveal event, slot props and types. `@awesome-reveal/vue` exports two components and two directives. They take the same [options](/reference/options/), as props or as an object. For the supported versions, see [Requirements](/getting-started/#requirements). ```js import { Cascade, Reveal, vCascade, vReveal } from "@awesome-reveal/vue"; ``` ## Reveal [Section titled “Reveal”](#reveal) Renders an element around its default slot, and reveals the element when it enters the viewport. ```vue Hello ``` * **Props**: `as`, `from`, `keyframes`, `duration`, `delay`, `threshold` and `when`. See [Options](/reference/options/). * **Other attributes**: the component gives them to the rendered element, for example `class` and `id`. * **`reveal` event**: the component emits it with the element when the reveal starts. See [Run code when the reveal starts](/guides/reveal-events/#run-code-when-the-reveal-starts). * **`revealed` slot prop**: `true` after the reveal. See [Read the revealed state](/guides/reveal-events/#read-the-revealed-state). Vue does not change an absent [`when`](/reference/options/#when) to `false`. ## Cascade [Section titled “Cascade”](#cascade) Renders an element around its default slot. When the element enters the viewport, it reveals the direct element children one after the other. See [Animate a list](/guides/lists/). `Cascade` accepts the props of `Reveal`, and [`interval`](/reference/options/#interval). It has the same event and slot prop. ## v-reveal [Section titled “v-reveal”](#v-reveal) Reveals the element that has the directive. ```vue

    A card
    ``` * **Value**: an object with the options of `Reveal`, except `as`. It also accepts `onReveal`. With no value, the directive uses the default options. * **Updates**: the directive watches the object deeply, so it also sees a change to a nested value. For the time when a change applies, see [Change the timing](/guides/timing/#reveal-later-with-a-threshold). * **Server rendering**: the directive renders the element hidden in the server HTML. See [Vue SSR and Nuxt](/frameworks/vue-ssr-nuxt/). ## v-cascade [Section titled “v-cascade”](#v-cascade) Reveals the direct element children of the element that has the directive. It accepts the options of `v-reveal`, and [`interval`](/reference/options/#interval). To use the directives with no import, register them globally. See [Vue SSR and Nuxt](/frameworks/vue-ssr-nuxt/). ## Stylesheet [Section titled “Stylesheet”](#stylesheet) The package imports its stylesheet. It also exports the stylesheet as `@awesome-reveal/vue/reveal.css`, for the [setups that need an import](/concepts/server-rendering/#hidden-in-the-server-html). ## Types [Section titled “Types”](#types) | Type | Description | | ---------------- | ------------------------------------------------------- | | `RevealProps` | The props of `Reveal`. | | `CascadeProps` | The props of `Cascade`. | | `RevealOptions` | The value of `v-reveal`. | | `CascadeOptions` | The value of `v-cascade`. | | `Side` | The sides of [`from`](/reference/options/#from). | | `StartState` | The [start state](/guides/entrances/) object of `from`. |
    The whole table reveals together.