react-animatable

Tiny(~1kB) animation hooks for React, built on Web Animations API.

Features

• Easy integration with a few lines of code. Works with any UI component libraries or CSS-in-JS libraries.
• Performant animation driven by native Web Animations API (WAAPI). Also supporting ScrollTimeline and ViewTimeline.
• Fully typed with TypeScript, which is stricter than TypeScript's lib.dom.d.ts.
• Tiny. Each hooks are ~1kB gzipped and the total is ~2kB gzipped.
• HTML, SVG, Canvas and anything can be animated.

Motivation

Animating something in React can be complicated than we expected, even with today's popular libraries. Web Animations API (WAAPI) looks like a brand-new promising way, because it's performant, it doesn't need JS runtime, it doesn't mutate style of DOM so it will not conflict with React's state, and it will become more convenient in the future (ScrollTimeline and ViewTimeline is an example). However using raw WAAPI with React is bit tricky and having risks of memory leak. This library is what to solve the problem.

Demo

https://inokawa.github.io/react-animatable/

Install

npm install react-animatable

Requirements

• react >= 16.14

If you use ESM and webpack 5, use react >= 18 to avoid Can't resolve react/jsx-runtime error.

And in some legacy browsers that does not support Web Animations API, you may need to use polyfill.

If you use ScrollTimeline or ViewTimeline, check browser support.

Usage

1. Define your animation with useAnimation hook.

The hooks accepts canonical keyframe format objects and KeyframeEffect's options as arguments, so check them before using this library.

2. Pass the return value of useAnimation to ref of element you want to control.

3. Call play()!

import { useEffect } from "react";
import { useAnimation } from "react-animatable";

export const App = () => {
  // 1. Define your animation in WAAPI way
  const animate = useAnimation(
    [{ transform: "rotate(0deg)" }, { transform: "rotate(720deg)" }],
    {
      duration: 1000,
      easing: "ease-in-out",
    }
  );

  return (
    <button
      // 2. You have to pass animate to element you want to control
      ref={animate}
      onClick={() => {
        // 3. And play it!
        animate.play();
      }}
    >
      Click Me!
    </button>
  );
};

Dynamic keyframe

Use prev and args for dynamic keyframe generation.

import { useEffect } from "react";
import { useAnimation } from "react-animatable";

export const App = () => {
  // Define argument type
  const animate = useAnimation<{ x: number; y: number }>(
    (prev, args) => [
      // You can get current style from 1st argument
      { transform: prev.transform },
      // Get passed position from 2nd argument
      { transform: `translate(${args.x}px, ${args.y}px)` },
    ],
    {
      duration: 400,
      easing: "ease-in-out",
    }
  );

  useEffect(() => {
    // If you click somewhere, the circle follows you!

    const onClick = (e: MouseEvent) => {
      // Pass mouse position when animate
      animate.play({ args: { x: e.clientX, y: e.clientY } });
    };
    window.addEventListener("click", onClick);
    return () => {
      window.removeEventListener("click", onClick);
    };
  }, []);

  return (
    <div
      ref={animate}
      style={{
        position: "fixed",
        border: "solid 0.1rem #135569",
        borderRadius: "50%",
        height: "6rem",
        width: "6rem",
        top: "-3rem",
        left: "-3rem",
      }}
    />
  );
};

Animation without CSS

Use useAnimationFunction for JS only animation.

import { useState } from "react";
import { useAnimationFunction } from "react-animatable";

export const App = () => {
  const [value, setValue] = useState(0);
  const animate = useAnimationFunction<number>(
    ({ progress }, arg) => {
      // Do anything here!
      setValue(progress * arg);
    },
    {
      duration: 600,
      easing: "ease-in-out",
    }
  );
  useEffect(() => {
    animate.play({ args: 100 });
  }, []);

  return <progress value={value} max={100} style={{ width: 600 }} />;
};

And see examples for more usages.

Documentation

• API reference

Use polyfill

1. browsers that have KeyframeEffect
2. browsers that have Element.animate()
3. browsers that have no Web Animations APIs

In 1, you can use all functions of this library without polyfill. Some of the newer features like composite mode and CSS Motion Path may be ignored in some browsers though.

In 2, you can use this library but useAnimationFuction would not work.

In 3, you have to setup Web Animations API polyfill to use this library.

Setup web-animations-js

npm install web-animations-js

// You can polyfill always
import "web-animations-js";
ReactDOM.render(<App />);

// or polyfill only if browser does not support Web Animations API
(async () => {
  if (!("animate" in document.body)) {
    await import("web-animations-js");
  }
  ReactDOM.render(<App />);
})();

Partial keyframes are not supported error was thrown

web-animations-js does not support partial keyframes, so you have to write animation definitions like below.

PolymerElements/paper-ripple#28 (comment)

// valid
const animate = useAnimation(
  [
    { transform: "translate3d(0px, 0, 0)" },
    { transform: "translate3d(400px, 0, 0)" },
  ],
  { duration: 800, easing: "ease-in-out" }
);
// invalid
const animate = useAnimation(
  { transform: "translate3d(400px, 0, 0)" },
  { duration: 800, easing: "ease-in-out" }
);

// valid
const animate = useAnimation(
  [
    { transform: "translateX(0px)", fill: "blue" },
    { transform: "translateX(100px)", fill: "red" },
    { transform: "translateX(0px)", fill: "blue" },
  ],
  { duration: 800, easing: "ease-in-out" }
);
// invalid
const animate = useAnimation(
  [
    { transform: "translateX(0px)" },
    { transform: "translateX(100px)", fill: "red" },
    { fill: "blue" },
  ],
  { duration: 800, easing: "ease-in-out" }
);

Contribute

All contributions are welcome. If you find a problem, feel free to create an issue or a PR.

Making a Pull Request

1. Fork this repo.
2. Run npm install.
3. Commit your fix.
4. Make a PR and confirm all the CI checks passed.

My previous experiments (deprecated)

• tweened
• react-use-d3