React

@awesome-reveal/react 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.

@awesome-reveal/react/keyframes does not import React. See Keyframes.

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 { ref, style, revealed }:

• ref: attach it to the element to reveal.
• style: the style that hides the element until the reveal. Spread it last into the element style, so that it overrides your opacity.
• revealed: true while the element is revealed. With once: false or when, it can go back to false.

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

function Card() {
  const { ref, style, revealed } = useReveal({
    keyframes: fade(),
    threshold: 0.3,
  });
  return (
    <article
      ref={ref}
      style={{ padding: 16, ...style }}
      data-reveal={revealed ? undefined : "hidden"}
    >
      …
    </article>
  );
}

data-reveal="hidden" lets a <noscript> style 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.

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, and the when option.

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.

TypeScript

@awesome-reveal/react exports these types:

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

@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 style into its style. 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.