`.** 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`. |