Tiny(~1kB) animation hooks for React, built on Web Animations API.
MIT License
Tiny(~1kB) animation hooks for React, built on Web Animations API.
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.
https://inokawa.github.io/react-animatable/
npm install react-animatable
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.
useAnimation
hook.The hooks accepts canonical keyframe format objects and KeyframeEffect's options as arguments, so check them before using this library.
Pass the return value of useAnimation
to ref
of element you want to control.
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>
);
};
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",
}}
/>
);
};
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.
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.
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 thrownweb-animations-js does not support partial keyframes, so you have to write animation definitions like below.
https://github.com/PolymerElements/paper-ripple/issues/28#issuecomment-266945027
// 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" }
);
All contributions are welcome. If you find a problem, feel free to create an issue or a PR.
npm install
.