react-awesome-reveal

React Awesome Reveal

React Awesome Reveal is a library for React apps written in TypeScript that adds reveal animations using the Intersection Observer API to detect when the elements appear in the viewport. Animations are internally provided by Emotion and implemented as CSS Animations to benefit from hardware acceleration.

Table Of Contents

• Features
• Demo
• Installation
• Quick Start
• Supported Effects
  • Attention Seekers
  • Props
  • Example
  • Chaining Multiple Animations
• Custom Animations
  • Other Props
• Past Releases
• License

Features

• 🎁 Modern stack – It is built for modern React
• 🏷 TypeScript support – It is written in TypeScript to improve the DX
• 🍃 Lightweight – Very little footprint on your project and no other dependencies required
• ⚙️ Uses native APIs – Intersection Observer and CSS Animations are now supported by all major browsers
• 🚀 Fast – Buttery smooth experience thanks to the use of native asynchronous APIs and hardware acceleration
• 💻 SSR support – Server Side Rendering works out-of-the-box
• 🌳 Tree-shakeable – Only the parts you use will be included in your final bundle

Demo

You can find a demo website here.

Installation

To add this package as a dependency to your app, simply run

npm install react-awesome-reveal --save

or, if you are using Yarn (as I strongly suggest):

yarn add react-awesome-reveal

Quick Start

Import effects from React Awesome Reveal to your React component, for example the Fade effect:

import { Fade } from "react-awesome-reveal";

Then simply wrap the components you want to animate:

<Fade>
  <p>I will gently appear as I enter the viewport</p>
</Fade>

Supported Effects

The effects currently supported are Bounce, Fade, Flip, Hinge, JackInTheBox, Roll, Rotate, Slide and Zoom. Refer to the Animate.css documentation for the details.

Attention Seekers

Since version 3, attention seeker animations are wrapped by the AttentionSeeker component, which accepts a prop called effect that specifies the animation to render (defaults to "bounce”). The supported effects are: ”bounce", "flash", "headShake”, "heartBeat", "jello”, "pulse", "rubberBand", “shake”, “shakeX", "shakeY”, "swing”, "tada" and “wobble”.

Again, refer to the Animate.css documentation for the details.

Props

You can pass the following props to the animation components to customize the behavior:

Prop	Description	Values	Default
cascade	If set, each child of a reveal animation automatically get assigned a delay that takes into account their predecessor (child i enters the viewport after i * delay * damping milliseconds) – useful for animating list items.	true or false	false
damping	Factor that affects the delay that each animated component in a cascade animation will be assigned. If damping = 1 then the delay will be equal to the animation duration; if damping < 1 then the delay will be lower than the animation duration; if damping > 1 then the delay will be greater than the animation duration.	number	0.5 (meaning that the delay will be half of the animation duration)
direction	Origin of the animation (where applicable).	Usually "down", "left", "right" or "up", with some exceptions documented in the code	undefined
delay	Time to wait before the animation starts (in milliseconds).	number	0
duration	The animation duration (milliseconds).	number	1000
fraction	How much an element should be in viewport before the animation is triggered.	number between 0 and 1	0
triggerOnce	Specifies if the animation should run only once or everytime an element enters/exits/re-enters the viewport.	true or false	false
className	The class names to add to the container element.	string	undefined
style	The inline styles to add to the container element.	React.CSSProperties	undefined
childCassName	The class names to add to the child element.	string	undefined
childStyle	The inline styles to add to the child element.	React.CSSProperties	undefined

Example

To trigger the animation only the first time an element enters the viewport:

<Slide triggerOnce>
  <p>I will animate only the first time you see me</p>
</Slide>

Chaining Multiple Animations

To chain together multiple animations, set the cascade prop to true:

<Fade cascade>
  <p>I enter first...</p>
  <p>...then comes my turn...</p>
  <p>...and finally you see me!</p>
</Fade>

This is almost equivalent to

<Fade>
  <p>I enter first...</p>
</Fade>
<Fade delay={1000}>
  <p>...then comes my turn...</p>
</Fade>
<Fade delay={2000}>
  <p>...and finally you see me!</p>
</Fade>

with the exception that, since each Fade component creates an isolated visibility context, in the second snippet every p will be shown only if they are inside the viewport (after the specified delay).

Custom Animations

Starting from version 3.2.0, you can define custom animations! Simply import the Reveal component (which is the default export of the library) and pass it a keyframes prop:

import React from "react";
import Reveal from "react-awesome-reveal";
import { keyframes } from "@emotion/core";

const customAnimation = keyframes`
  from {
    opacity: 0;
    transform: translate3d(-200px, -100px, 0);
  }
  to {
    opacity: 1;
    transform: translate3d(0, 0, 0);
  }
`;

function MyAnimatedComponent({children}) {
  return (
    <Reveal keyframes={customAnimation}>
      {children}
    </Reveal>;
  );
}

If no keyframes prop is passed, the default rendered animation is a fading entrance from the left (equivalent to <Fade direction="left">...</Fade>).

Other Props

You can also pass these props to Reveal:

• cascade
• damping
• delay
• duration
• fraction
• triggerOnce
• className and childClassName
• style and childStyle

Past Releases

To see the documentation for previous versions, navigate through past tags in the GitHub's project repository and read the README for that specific version.

License

Project source code is licensed under the MIT license. You are free to fork this repository, edit the code, share and use it both for non-commercial and commercial purposes.