Skip to content

React reveal API: components and hooks

@awesome-reveal/react exports two components and two hooks. They take the same options, as props or as an object. For the supported versions, see Requirements.

import { Cascade, Reveal, useCascade, useReveal } from "@awesome-reveal/react";

Renders an element around its children, and reveals the element when it enters the viewport.

<Reveal as="section" from="left" className="hero">
Hello
</Reveal>
  • Props: as, from, keyframes, duration, delay, threshold, when and onReveal. See 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.

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.

Cascade accepts the props of Reveal, and interval.

Reveals an element that you render, with no wrapper element.

import { useReveal } from "@awesome-reveal/react";
export function Card() {
const { getProps, revealed } = useReveal<HTMLElement>({ from: "left" });
return (
<article {...getProps({ className: "card" })}>
{revealed ? "Hello" : "Waiting"}
</article>
);
}
  • Parameter: the options of Reveal, except as.
  • Type parameter: the type of the element. The default is HTMLElement.
  • Return value: a RevealState.

Reveals the direct element children of an element that you render. It accepts the options of useReveal, and interval. It returns a RevealState.

The hooks return an object with two members.

getProps<P extends object>(
props?: P & { ref?: Ref<T> },
): Omit<P, "ref"> & RevealTargetProps<T>

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

Type: boolean.

true after the reveal. It is false in the server render. See Read the revealed state.

To use Reveal, Cascade and the hooks with Server Components, see Next.js.

The package imports its stylesheet. It also exports the stylesheet as @awesome-reveal/react/reveal.css, for the setups that need an import.

Type Description
RevealProps<T> The props of Reveal. T is the tag, and the default is "div".
CascadeProps<T> The props of Cascade.
RevealOptions The options of useReveal.
CascadeOptions The options of useCascade.
RevealState<T> The return value of the hooks. T is the type of the element.
RevealTargetProps<T> The props that getProps() adds: ref and data-awesome-reveal.
Side The sides of from.
StartState The start state object of from.