react-use-controllable-animation

A React hook for creating animations with start/pause/stop/reset controls

Installation

npm install react-use-controllable-animation

How to Use

Import or require the default export useControllableAnimation. The module also exports easingFunctions if needed by your application.

Parameters

The hook accepts an object with the following parameters: | Parameter | type | default | description | |-----------|---------|------------------------------|--------------------------------------------------------------------------------------------------------------------------| | autoplay | boolean | true | Specify if the animation should begin on initialization | alternate | boolean | false | Specify if the animation should run backwards every other loop (i.e. loop 1: 0 -> 1, loop 2: 1 -> 0) | alternateDelay | boolean | false | Specify if the delay should be applied on every loop or every other loop (only affects animation if alternate is set to true) | delay | number | 0 | Amount of time in ms to delay the animation | duration | number | 1000 | Duration of the animation in ms | easing | string or function | "linear" | Specify the name of the easing function to use (must be one of the keys exported in easingFunctions) or define your own custom easing function ((val: number[0-1]) => number[0-1]) | loops | number | Infinity | Number of times animation should run before stopping (Note: alternating animations count each 0-1 or 1-0 as a loop) | onFinish | function | undefined | Callback to be run after the animation completes running loops times | onLoop | function | undefined | Callback to be run after each loop completes. Passes current loop as argument. | onProgress | function | | Callback to be run on each frame. Passes progress (with easing) and an object including uneasedProgress, progressWithDelay, and loop as arguments.

Returns

The hook returns an object with the following function properties:

start - begins/unpauses the animation if it's not already running

pause - pauses the animation on the current frame

reset - resets the animation to the initial state (progress = 0, loop = 0) without starting or pausing the animation

stop - pauses the animation and resets it

Example

import { useCallback, useEffect, useState } from "react";
import useControllableAnimation, { easingFunctions } from "react-use-controllable-animation";

function Example() {
  const [ bounceEl, setBounceEl ] = useState();
  const [ sineEl, setSineEl ] = useState();
  
  const onProgress = useCallback((progress, { uneasedProgress, progressWithDelay, loop }) => {
    if (!bounceEl || !sineEl) return;
    
    bounceEl.style.left = `${(progress * 100).toFixed(2)}%`;
    sineEl.style.left = `${(easingFunctions.easeInOutSine(uneasedProgress)) * 100).toFixed(2)}%`;
    
    console.log(`Overall animation progress including delay time: ${progressWithDelay}`);
    console.log(`Current loop: ${loop}`);
  }, [ bounceEl, sineEl ]);
  
  const { start, pause, reset, stop } = useControllableAnimation({
    autoplay: !!bounceEl && !!sineEl,
    alternate: true,
    alternateDelay: true,
    delay: 1000,
    duration: 2000,
    easing: "easeInBounce",
    onProgress
  });
  
  return (
    <div>
      <div ref={setBounceEl}/>
      <div ref={setSineEl}/>
      <button onClick={start}>START</button>
      <button onClick={pause}>PAUSE</button>
      <button onClick={reset}>RESET</button>
      <button onClick={stop}>STOP</button>
    </div>
  );
}
    

Demo

The package includes a demo found in the example folder. You can either build it yourself (npm install react-use-controllable-animation && npm run start), or view a live version at this link:

https://react-use-controllable-animation.netlify.app

Enjoy