{"id":13422274,"url":"https://github.com/inokawa/react-animatable","last_synced_at":"2025-04-09T20:15:31.520Z","repository":{"id":37206863,"uuid":"493635306","full_name":"inokawa/react-animatable","owner":"inokawa","description":"Tiny(~1kB) animation hooks for React, built on Web Animations API.","archived":false,"fork":false,"pushed_at":"2024-12-01T11:28:19.000Z","size":58251,"stargazers_count":49,"open_issues_count":11,"forks_count":1,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-04-09T20:15:18.924Z","etag":null,"topics":["animation","canvas","css","d3","react","react-animations","react-component","react-hooks","scroll-timeline","svg","transition","tween","web-animations","web-animations-api"],"latest_commit_sha":null,"homepage":"https://inokawa.github.io/react-animatable/","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/inokawa.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null},"funding":{"github":["inokawa"]}},"created_at":"2022-05-18T11:32:53.000Z","updated_at":"2025-02-11T15:51:41.000Z","dependencies_parsed_at":"2022-07-10T16:02:31.798Z","dependency_job_id":"e032322d-24d0-4264-895a-b862374df123","html_url":"https://github.com/inokawa/react-animatable","commit_stats":{"total_commits":394,"total_committers":3,"mean_commits":"131.33333333333334","dds":0.1725888324873096,"last_synced_commit":"de3b33f197cba280ee098ac5a67279369c251d1d"},"previous_names":[],"tags_count":48,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/inokawa%2Freact-animatable","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/inokawa%2Freact-animatable/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/inokawa%2Freact-animatable/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/inokawa%2Freact-animatable/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/inokawa","download_url":"https://codeload.github.com/inokawa/react-animatable/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248103872,"owners_count":21048245,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["animation","canvas","css","d3","react","react-animations","react-component","react-hooks","scroll-timeline","svg","transition","tween","web-animations","web-animations-api"],"created_at":"2024-07-30T23:00:40.914Z","updated_at":"2025-04-09T20:15:31.499Z","avatar_url":"https://github.com/inokawa.png","language":"TypeScript","readme":"# react-animatable\n\n![npm](https://img.shields.io/npm/v/react-animatable) ![npm bundle size](https://img.shields.io/bundlephobia/minzip/react-animatable) [![check](https://github.com/inokawa/react-animatable/actions/workflows/check.yml/badge.svg)](https://github.com/inokawa/react-animatable/actions/workflows/check.yml) [![demo](https://github.com/inokawa/react-animatable/actions/workflows/demo.yml/badge.svg)](https://github.com/inokawa/react-animatable/actions/workflows/demo.yml)\n\nTiny(~1kB) animation hooks for [React](https://github.com/facebook/react), built on [Web Animations API](https://developer.mozilla.org/en-US/docs/Web/API/Web_Animations_API).\n\n\u003cimg src=\"./images/demo-chart.gif\" width=\"350px\" /\u003e\u003cimg src=\"./images/demo-scroll.gif\" width=\"350px\" /\u003e\n\n## Features\n\n- Easy integration with a few lines of code. Works with any UI component libraries or CSS-in-JS libraries.\n- 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).\n- 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).\n- Tiny. Each hooks are ~1kB gzipped and [the total is ~2kB gzipped](https://bundlephobia.com/package/react-animatable).\n- HTML, SVG, Canvas and anything can be animated.\n\n## Motivation\n\nAnimating 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.\n\n## Demo\n\nhttps://inokawa.github.io/react-animatable/\n\n## Install\n\n```sh\nnpm install react-animatable\n```\n\n### Requirements\n\n- react \u003e= 16.14\n\nIf you use ESM and webpack 5, use react \u003e= 18 to avoid [Can't resolve `react/jsx-runtime` error](https://github.com/facebook/react/issues/20235).\n\nAnd in some legacy browsers that does not support Web Animations API, [you may need to use polyfill](#use-polyfill).\n\nIf you use [ScrollTimeline](https://caniuse.com/?search=scrolltimeline) or [ViewTimeline](https://caniuse.com/?search=viewtimeline), check browser support.\n\n## Usage\n\n1. Define your animation with `useAnimation` hook.\n\n\u003e 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.\n\n2. Pass the return value of `useAnimation` to `ref` of element you want to control.\n\n3. Call `play()`!\n\n```tsx\nimport { useEffect } from \"react\";\nimport { useAnimation } from \"react-animatable\";\n\nexport const App = () =\u003e {\n  // 1. Define your animation in WAAPI way\n  const animate = useAnimation(\n    [{ transform: \"rotate(0deg)\" }, { transform: \"rotate(720deg)\" }],\n    {\n      duration: 1000,\n      easing: \"ease-in-out\",\n    }\n  );\n\n  return (\n    \u003cbutton\n      // 2. You have to pass animate to element you want to control\n      ref={animate}\n      onClick={() =\u003e {\n        // 3. And play it!\n        animate.play();\n      }}\n    \u003e\n      Click Me!\n    \u003c/button\u003e\n  );\n};\n```\n\n### Dynamic keyframe\n\nUse `prev` and `args` for dynamic keyframe generation.\n\n```tsx\nimport { useEffect } from \"react\";\nimport { useAnimation } from \"react-animatable\";\n\nexport const App = () =\u003e {\n  // Define argument type\n  const animate = useAnimation\u003c{ x: number; y: number }\u003e(\n    (prev, args) =\u003e [\n      // You can get current style from 1st argument\n      { transform: prev.transform },\n      // Get passed position from 2nd argument\n      { transform: `translate(${args.x}px, ${args.y}px)` },\n    ],\n    {\n      duration: 400,\n      easing: \"ease-in-out\",\n    }\n  );\n\n  useEffect(() =\u003e {\n    // If you click somewhere, the circle follows you!\n\n    const onClick = (e: MouseEvent) =\u003e {\n      // Pass mouse position when animate\n      animate.play({ args: { x: e.clientX, y: e.clientY } });\n    };\n    window.addEventListener(\"click\", onClick);\n    return () =\u003e {\n      window.removeEventListener(\"click\", onClick);\n    };\n  }, []);\n\n  return (\n    \u003cdiv\n      ref={animate}\n      style={{\n        position: \"fixed\",\n        border: \"solid 0.1rem #135569\",\n        borderRadius: \"50%\",\n        height: \"6rem\",\n        width: \"6rem\",\n        top: \"-3rem\",\n        left: \"-3rem\",\n      }}\n    /\u003e\n  );\n};\n```\n\n### Animation without CSS\n\nUse `useAnimationFunction` for JS only animation.\n\n```tsx\nimport { useState } from \"react\";\nimport { useAnimationFunction } from \"react-animatable\";\n\nexport const App = () =\u003e {\n  const [value, setValue] = useState(0);\n  const animate = useAnimationFunction\u003cnumber\u003e(\n    ({ progress }, arg) =\u003e {\n      // Do anything here!\n      setValue(progress * arg);\n    },\n    {\n      duration: 600,\n      easing: \"ease-in-out\",\n    }\n  );\n  useEffect(() =\u003e {\n    animate.play({ args: 100 });\n  }, []);\n\n  return \u003cprogress value={value} max={100} style={{ width: 600 }} /\u003e;\n};\n```\n\nAnd see [examples](./stories) for more usages.\n\n## Documentation\n\n- [API reference](./docs/API.md)\n\n## Use polyfill\n\n1. [browsers that have KeyframeEffect](https://caniuse.com/mdn-api_keyframeeffect)\n1. [browsers that have Element.animate()](https://caniuse.com/mdn-api_element_animate)\n1. browsers that have no Web Animations APIs\n\nIn 1, you can use all functions of this library without polyfill. Some of the newer features like [composite mode](https://caniuse.com/web-animation) and [CSS Motion Path](https://caniuse.com/css-motion-paths) may be ignored in some browsers though.\n\nIn 2, you can use this library but `useAnimationFuction` would not work.\n\nIn 3, you have to setup [Web Animations API polyfill](https://github.com/web-animations/web-animations-js) to use this library.\n\n### Setup web-animations-js\n\n```sh\nnpm install web-animations-js\n```\n\n```js\n// You can polyfill always\nimport \"web-animations-js\";\nReactDOM.render(\u003cApp /\u003e);\n\n// or polyfill only if browser does not support Web Animations API\n(async () =\u003e {\n  if (!(\"animate\" in document.body)) {\n    await import(\"web-animations-js\");\n  }\n  ReactDOM.render(\u003cApp /\u003e);\n})();\n```\n\n#### `Partial keyframes are not supported` error was thrown\n\nweb-animations-js does not support partial keyframes, so you have to write animation definitions like below.\n\nhttps://github.com/PolymerElements/paper-ripple/issues/28#issuecomment-266945027\n\n```jsx\n// valid\nconst animate = useAnimation(\n  [\n    { transform: \"translate3d(0px, 0, 0)\" },\n    { transform: \"translate3d(400px, 0, 0)\" },\n  ],\n  { duration: 800, easing: \"ease-in-out\" }\n);\n// invalid\nconst animate = useAnimation(\n  { transform: \"translate3d(400px, 0, 0)\" },\n  { duration: 800, easing: \"ease-in-out\" }\n);\n\n// valid\nconst animate = useAnimation(\n  [\n    { transform: \"translateX(0px)\", fill: \"blue\" },\n    { transform: \"translateX(100px)\", fill: \"red\" },\n    { transform: \"translateX(0px)\", fill: \"blue\" },\n  ],\n  { duration: 800, easing: \"ease-in-out\" }\n);\n// invalid\nconst animate = useAnimation(\n  [\n    { transform: \"translateX(0px)\" },\n    { transform: \"translateX(100px)\", fill: \"red\" },\n    { fill: \"blue\" },\n  ],\n  { duration: 800, easing: \"ease-in-out\" }\n);\n```\n\n## Contribute\n\nAll contributions are welcome.\nIf you find a problem, feel free to create an [issue](https://github.com/inokawa/react-animatable/issues) or a [PR](https://github.com/inokawa/react-animatable/pulls).\n\n### Making a Pull Request\n\n1. Fork this repo.\n2. Run `npm install`.\n3. Commit your fix.\n4. Make a PR and confirm all the CI checks passed.\n\n## My previous experiments (deprecated)\n\n- [tweened](https://github.com/inokawa/tweened)\n- [react-use-d3](https://github.com/inokawa/react-use-d3)\n","funding_links":["https://github.com/sponsors/inokawa"],"categories":["UI Animation"],"sub_categories":["Form Components"],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Finokawa%2Freact-animatable","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Finokawa%2Freact-animatable","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Finokawa%2Freact-animatable/lists"}