@play-when-visible/react-spring

An npm package for playing React Spring animations when they become visible in the viewport.

Features

• 🎣 Hooks Support
• 🎥 Render Props Support
• 🛠 Typescript Support
• ⚙ Highly Configurable
• 🙂 Easy to Use

Installation

Install the package via your favorite package manager.

npm install @play-when-visible/react-spring

or

yarn add @play-when-visible/react-spring

Make sure to also have react-spring included in your project.

npm install react-spring

or

yarn add react-spring

Usage

Hooks API

@play-when-visible/react-spring provides a set of hooks prefixed with usePWV to create animations. The hooks return a tuple [ref, animation] that contains the ref the animation. For example...

import React from "react";
import { animated } from "react-spring";
import { usePWVSpring } from "@play-when-visible/react-spring";

const Page = () => {
    const [ref, animation] = usePWVSpring({
        animation: {
            from: {
                opacity: 0,
            },
            to: {
                opacity: 1,
            },
            config: {
                tension: 50,
                velocity: 12,
            },
        },
    });

    return (
        <div ref={ref}>
            <animated.h1 style={animation}>Hello World!</animated.h1>
        </div>
    );
};

WARNING! It is VERY important that you do not put the ref directly on an animated tag or multiple hooks will NOT WORK!

Render Props API

@play-when-visible/react-spring provides a set of components prefixed with PWV to create animations. They work by taking in a child function that passes an object in containing the animation. For example...

import React from "react";
import { animated } from "react-spring";
import { PWVSpring } from "@play-when-visible/react-spring";

const Page = () => {
    return (
        <PWVSpring
            animation={{
                from: {
                    opacity: 0,
                },
                to: {
                    opacity: 1,
                },
                config: {
                    tension: 50,
                    velocity: 12,
                },
            }}
        >
            {({ animation }) => (
                <animated.div style={animation}>Hello World!</animated.div>
            )}
        </PWVSpring>
    );
};

API

WARNING! It is VERY important that you do not put the ref directly on an animated tag or multiple hooks will NOT WORK!

This table applies to both the Hooks API and the Render Props API.

Prop	Default Value	Required	Description
animation	undefined	true	The animation to be played when the component becomes visible in the viewport. Accepts from, to, and config.
onlyOnce	false	false	If true, the animation plays only once.
sensorOptions	undefined	false	The sensor options for react-intersection-observer. Read more in the react-intersection-observer documentation.
onStart	undefined	false	Callback for when the animation starts playing.
onRest	undefined	false	Callback for when the animation stops playing.
onVisibilityChange	undefined	false	Callback for when the animation becomes visible or invisible in the viewport.

Render Props API Only

Prop	Default Value	Required	Description
as	div	false	The primitive tag to wrap the animation around.
children	undefined	true	The child function {( animation }) => (...your jsx here)}