8 |
9 | ## Features
10 |
11 | - Easy integration with a few lines of code. Works with any UI component libraries or CSS-in-JS libraries.
12 | - Performant animation driven by native [Web Animations API (WAAPI)](https://developer.mozilla.org/en-US/docs/Web/API/Web_Animations_API). Also supporting [ScrollTimeline](https://developer.mozilla.org/en-US/docs/Web/API/ScrollTimeline) and [ViewTimeline](https://developer.mozilla.org/en-US/docs/Web/API/ViewTimeline).
13 | - Fully typed with [TypeScript](https://www.typescriptlang.org/), which is stricter than TypeScript's [lib.dom.d.ts](https://github.com/microsoft/TypeScript/blob/main/lib/lib.dom.d.ts).
14 | - Tiny. Each hooks are ~1kB gzipped and [the total is ~2kB gzipped](https://bundlephobia.com/package/react-animatable).
15 | - HTML, SVG, Canvas and anything can be animated.
16 |
17 | ## Motivation
18 |
19 | Animating something in React can be complicated than we expected, even with today's popular libraries. [Web Animations API (WAAPI)](https://developer.mozilla.org/en-US/docs/Web/API/Web_Animations_API) 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](https://developer.mozilla.org/en-US/docs/Web/API/ScrollTimeline) and [ViewTimeline](https://developer.mozilla.org/en-US/docs/Web/API/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.
20 |
21 | ## Demo
22 |
23 | https://inokawa.github.io/react-animatable/
24 |
25 | ## Install
26 |
27 | ```sh
28 | npm install react-animatable
29 | ```
30 |
31 | ### Requirements
32 |
33 | - react >= 16.14
34 |
35 | If you use ESM and webpack 5, use react >= 18 to avoid [Can't resolve `react/jsx-runtime` error](https://github.com/facebook/react/issues/20235).
36 |
37 | And in some legacy browsers that does not support Web Animations API, [you may need to use polyfill](#use-polyfill).
38 |
39 | If you use [ScrollTimeline](https://caniuse.com/?search=scrolltimeline) or [ViewTimeline](https://caniuse.com/?search=viewtimeline), check browser support.
40 |
41 | ## Usage
42 |
43 | 1. Define your animation with `useAnimation` hook.
44 |
45 | > The hooks accepts [canonical keyframe format objects](https://developer.mozilla.org/en-US/docs/Web/API/Web_Animations_API/Keyframe_Formats#syntax) and [KeyframeEffect's options](https://developer.mozilla.org/en-US/docs/Web/API/KeyframeEffect/KeyframeEffect#parameters) as arguments, so check them before using this library.
46 |
47 | 2. Pass the return value of `useAnimation` to `ref` of element you want to control.
48 |
49 | 3. Call `play()`!
50 |
51 | ```tsx
52 | import { useEffect } from "react";
53 | import { useAnimation } from "react-animatable";
54 |
55 | export const App = () => {
56 | // 1. Define your animation in WAAPI way
57 | const animate = useAnimation(
58 | [{ transform: "rotate(0deg)" }, { transform: "rotate(720deg)" }],
59 | {
60 | duration: 1000,
61 | easing: "ease-in-out",
62 | }
63 | );
64 |
65 | return (
66 |
76 | );
77 | };
78 | ```
79 |
80 | ### Dynamic keyframe
81 |
82 | Use `prev` and `args` for dynamic keyframe generation.
83 |
84 | ```tsx
85 | import { useEffect } from "react";
86 | import { useAnimation } from "react-animatable";
87 |
88 | export const App = () => {
89 | // Define argument type
90 | const animate = useAnimation<{ x: number; y: number }>(
91 | (prev, args) => [
92 | // You can get current style from 1st argument
93 | { transform: prev.transform },
94 | // Get passed position from 2nd argument
95 | { transform: `translate(${args.x}px, ${args.y}px)` },
96 | ],
97 | {
98 | duration: 400,
99 | easing: "ease-in-out",
100 | }
101 | );
102 |
103 | useEffect(() => {
104 | // If you click somewhere, the circle follows you!
105 |
106 | const onClick = (e: MouseEvent) => {
107 | // Pass mouse position when animate
108 | animate.play({ args: { x: e.clientX, y: e.clientY } });
109 | };
110 | window.addEventListener("click", onClick);
111 | return () => {
112 | window.removeEventListener("click", onClick);
113 | };
114 | }, []);
115 |
116 | return (
117 |
129 | );
130 | };
131 | ```
132 |
133 | ### Animation without CSS
134 |
135 | Use `useAnimationFunction` for JS only animation.
136 |
137 | ```tsx
138 | import { useState } from "react";
139 | import { useAnimationFunction } from "react-animatable";
140 |
141 | export const App = () => {
142 | const [value, setValue] = useState(0);
143 | const animate = useAnimationFunction27 | Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do 28 | eiusmod tempor incididunt ut labore et dolore magna aliqua. Risus quis 29 | varius quam quisque id. Et ligula ullamcorper malesuada proin libero 30 | nunc consequat interdum varius. Elit ullamcorper dignissim cras 31 | tincidunt lobortis feugiat vivamus at augue. 32 |
33 |34 | Dolor sed viverra ipsum nunc aliquet. Sed sed risus pretium quam 35 | vulputate dignissim. Tortor aliquam nulla facilisi cras. A erat nam at 36 | lectus urna duis convallis convallis. Nibh ipsum consequat nisl vel 37 | pretium lectus. Sagittis aliquam malesuada bibendum arcu vitae 38 | elementum. Malesuada bibendum arcu vitae elementum curabitur vitae 39 | nunc sed velit. 40 |
41 | 50 |51 | Adipiscing enim eu turpis egestas pretium aenean pharetra magna ac. 52 | Arcu cursus vitae congue mauris rhoncus aenean vel. Sit amet cursus 53 | sit amet dictum. Augue neque gravida in fermentum et. Gravida rutrum 54 | quisque non tellus orci ac auctor augue mauris. Risus quis varius quam 55 | quisque id diam vel quam elementum. Nibh praesent tristique magna sit 56 | amet purus gravida quis. Duis ultricies lacus sed turpis tincidunt id 57 | aliquet. In egestas erat imperdiet sed euismod nisi. Eget egestas 58 | purus viverra accumsan in nisl nisi scelerisque. Netus et malesuada 59 | fames ac. 60 |
61 |