React

@awesome-reveal/react needs React 18 or later. It has two APIs with the same options:

• The Reveal component renders one element and animates it.
• The useReveal hook animates your own element or component, with no wrapper.

To install the package, see Getting started.

Entry points

Import path	Contents
@awesome-reveal/react	The Reveal component and the useReveal hook.
@awesome-reveal/react/keyframes	The built-in keyframes, defineKeyframes, and their types.

Tip

@awesome-reveal/react/keyframes does not import React, so you can call the factories in a Server Component. See React Server Components.

The Reveal component

Reveal renders one element around its children. as sets the tag, and the default is div. Reveal gives its other props and its ref to that element:

import { useRef } from "react";
import { Reveal } from "@awesome-reveal/react";
import { fade, slide } from "@awesome-reveal/react/keyframes";

function Hero() {
  const inputRef = useRef(null);

  return (
    <Reveal as="section" keyframes={slide()} className="hero" id="intro">
      <Reveal as="input" keyframes={fade()} ref={inputRef} />
    </Reveal>
  );
}

In TypeScript, the props and the ref type follow as.

The children animate together. To animate them one after the other, use stagger.

The useReveal hook

useReveal(options) returns { revealed, getProps }:

• revealed: true while the element is revealed. With once: false or when, it can go back to false.
• getProps(props?): merges the reveal into the props of the element. It returns the ref, the style with the hidden opacity, and data-reveal. Spread the result on the element.

import { useReveal } from "@awesome-reveal/react";
import { fade } from "@awesome-reveal/react/keyframes";

function Card() {
  const { getProps } = useReveal({
    keyframes: fade(),
    threshold: 0.3,
  });

  return (
    <article {...getProps({ className: "card", style: { padding: 16 } })}>
      …
    </article>
  );
}

Pass your own ref and style to getProps, not next to the spread. getProps merges them. A style after the spread replaces the hidden style, and the element shows before the reveal.

getProps sets data-reveal="hidden" while the element is hidden. A <noscript> style can use it to show the element when JavaScript does not run. See Pages without JavaScript.

Use revealed to run code after the reveal, for example in a useEffect.

To use getProps on your own component, forward the ref to an element. React 18 needs forwardRef for this.

With stagger, always render the children. Children that you render only when revealed is true do not animate.

The element type is HTMLElement by default. For another element, give the type, for example useReveal<SVGSVGElement>().

Options

Reveal and useReveal accept the reveal options.

Control the reveal manually

With when, your code controls the reveal, and nothing observes the viewport:

• when={false} hides the element.
• when={true} reveals the element and plays the animation.
• A change from true to false hides the element again.

function Results({ data }) {
  return (
    <Reveal as="ul" when={data !== undefined} stagger={50}>
      {data?.map((item) => (
        <li key={item.id}>{item.name}</li>
      ))}
    </Reveal>
  );
}

With when, threshold, rootMargin and once have no effect. For the rest of the rules, such as the flash after hydration, see Control the reveal manually. For the effect of a changed option, see Option changes.

TypeScript

@awesome-reveal/react exports these types:

• RevealProps<T>: the props of Reveal, where T is the tag in as.
• RevealOptions: the reveal options.
• RevealState<T>: the return value of useReveal.
• RevealTargetProps<T>: the return value of getProps.

@awesome-reveal/react/keyframes exports the keyframes types, such as KeyframesFactory and SlideOptions. See Keyframes.

SSR

On the server, Reveal renders the element hidden, with opacity: 0, unless when is true. With useReveal, the element is hidden when you spread getProps() on it: it sets the hidden style and data-reveal="hidden". The animation starts in the browser, when the element enters the viewport. If JavaScript does not run, the element stays hidden. To show it, add the <noscript> style.

React Server Components

Reveal and useReveal are client code, with the "use client" directive. You can render Reveal in a Server Component.

The keyframes factories do not import React. You can call them in a Server Component, and give the result to Reveal:

import { Reveal } from "@awesome-reveal/react";
import { slide } from "@awesome-reveal/react/keyframes";

export default function Page() {
  return (
    <Reveal keyframes={slide({ direction: "left" })}>
      <h1>Rendered on the server</h1>
    </Reveal>
  );
}

A keyframes array is plain data, so React can send it from the server to the client. A function cannot go to a Client Component. Call the factory on the server. Then give its result to Reveal.

If you call spring() on the server, browsers without CSS linear() show the element with no animation. See Springs.