{"id":13450274,"url":"https://github.com/wellyshen/use-web-animations","last_synced_at":"2025-05-15T05:08:21.490Z","repository":{"id":37715597,"uuid":"268840316","full_name":"wellyshen/use-web-animations","owner":"wellyshen","description":"😎 🍿 React hook for highly-performant and manipulable animations using Web Animations API.","archived":false,"fork":false,"pushed_at":"2023-08-12T16:38:17.000Z","size":3785,"stargazers_count":1277,"open_issues_count":24,"forks_count":27,"subscribers_count":7,"default_branch":"master","last_synced_at":"2025-04-29T19:36:31.079Z","etag":null,"topics":["animation","hook","interaction","motion","performance","playback-control","react","transition","typescript","use-web-animations","ux","waapi","web-animations","web-animations-api"],"latest_commit_sha":null,"homepage":"https://use-web-animations.netlify.app","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/wellyshen.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null},"funding":{"github":null,"patreon":null,"open_collective":"use-web-animations","ko_fi":null,"tidelift":null,"community_bridge":null,"liberapay":null,"issuehunt":null,"otechie":null,"custom":null}},"created_at":"2020-06-02T15:36:21.000Z","updated_at":"2025-04-18T15:54:24.000Z","dependencies_parsed_at":"2023-09-23T14:37:54.419Z","dependency_job_id":null,"html_url":"https://github.com/wellyshen/use-web-animations","commit_stats":{"total_commits":757,"total_committers":4,"mean_commits":189.25,"dds":0.4795244385733157,"last_synced_commit":"8e3a4ed54910eb8271f42b06b7d7ab1da636baa1"},"previous_names":[],"tags_count":60,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wellyshen%2Fuse-web-animations","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wellyshen%2Fuse-web-animations/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wellyshen%2Fuse-web-animations/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wellyshen%2Fuse-web-animations/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/wellyshen","download_url":"https://codeload.github.com/wellyshen/use-web-animations/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":253149625,"owners_count":21861740,"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","hook","interaction","motion","performance","playback-control","react","transition","typescript","use-web-animations","ux","waapi","web-animations","web-animations-api"],"created_at":"2024-07-31T07:00:33.166Z","updated_at":"2025-05-15T05:08:21.451Z","avatar_url":"https://github.com/wellyshen.png","language":"TypeScript","funding_links":["https://opencollective.com/use-web-animations"],"categories":["Packages","TypeScript"],"sub_categories":[],"readme":"# \u003cem\u003e\u003cb\u003eUSE-WEB-ANIMATIONS\u003c/b\u003e\u003c/em\u003e\n\nUsing [Web Animations API](https://developer.mozilla.org/en-US/docs/Web/API/Web_Animations_API) (a.k.a WAAPI) in the React [hook](https://reactjs.org/docs/hooks-custom.html#using-a-custom-hook) way. Let's create highly-performant, flexible and manipulable web animations in the modern world. Hope you guys 👍🏻 it!\n\n❤️ it? ⭐️ it on [GitHub](https://github.com/wellyshen/use-web-animations/stargazers) or [Tweet](https://twitter.com/intent/tweet?text=With%20@wellyshen/use-web-animations,%20I%20can%20build%20fancy%20and%20performant%20animations%20for%20my%20web%20app.%20Thanks,%20@Welly%20Shen%20🤩) about it.\n\n[![build status](https://img.shields.io/github/workflow/status/wellyshen/use-web-animations/CI?style=flat-square)](https://github.com/wellyshen/use-web-animations/actions?query=workflow%3ACI)\n[![coverage status](https://img.shields.io/coveralls/github/wellyshen/use-web-animations?style=flat-square)](https://coveralls.io/github/wellyshen/use-web-animations?branch=master)\n[![npm version](https://img.shields.io/npm/v/@wellyshen/use-web-animations?style=flat-square)](https://www.npmjs.com/package/@wellyshen/use-web-animations)\n[![npm downloads](https://img.shields.io/npm/dm/@wellyshen/use-web-animations?style=flat-square)](https://www.npmtrends.com/@wellyshen/use-web-animations)\n[![npm downloads](https://img.shields.io/npm/dt/@wellyshen/use-web-animations?style=flat-square)](https://www.npmtrends.com/@wellyshen/use-web-animations)\n[![gzip size](https://badgen.net/bundlephobia/minzip/@wellyshen/use-web-animations?label=gzip%20size\u0026style=flat-square)](https://bundlephobia.com/result?p=@wellyshen/use-web-animations)\n[![All Contributors](https://img.shields.io/badge/all_contributors-1-orange.svg?style=flat-square)](#contributors-)\n[![PRs welcome](https://img.shields.io/badge/PRs-welcome-brightgreen?style=flat-square)](CONTRIBUTING.md)\n[![Twitter URL](https://img.shields.io/twitter/url?style=social\u0026url=https%3A%2F%2Fgithub.com%2Fwellyshen%2Fuse-web-animations)](https://twitter.com/intent/tweet?text=With%20@wellyshen/use-web-animations,%20I%20can%20build%20fancy%20and%20performant%20animations%20for%20my%20web%20app.%20Thanks,%20@Welly%20Shen%20🤩)\n\n![demo_basic](https://user-images.githubusercontent.com/21308003/91186058-280b7d00-e721-11ea-8180-e739d14c7ec7.gif)\n\n⚡️ Try yourself: https://use-web-animations.netlify.app\n\n![demo_animate](https://user-images.githubusercontent.com/21308003/91186066-2a6dd700-e721-11ea-84c5-b2c4ff984cf5.gif)\n\n⚡️ Try yourself: https://use-web-animations.netlify.app#animations\n\n## Features\n\n- 🚀 Animate on the Web with [highly-performant](https://web.dev/animations-overview/#css-js) and manipulable way, using [Web Animations API](https://developer.mozilla.org/en-US/docs/Web/API/Web_Animations_API).\n- 🎣 Easy to use, based on React [hook](https://reactjs.org/docs/hooks-custom.html#using-a-custom-hook).\n- 🎛 Super flexible [API](#api) design that can cover [all the cases](#usage) that you need.\n- 🎞 [Built-ins animations](#use-built-in-animations) for you, based on [Animate.css](https://animate.style).\n- 🔩 Supports custom `refs` for [some reasons](#use-your-own-ref).\n- 📜 Supports [TypeScript](https://www.typescriptlang.org) type definition.\n- 🗄️ Server-side rendering compatibility.\n- 🦔 Tiny size ([~ 4.4kB gzipped](https://bundlephobia.com/result?p=@wellyshen/use-web-animations)). No external dependencies, aside for the `react`.\n\n## Requirement\n\nTo use `use-web-animations`, you must use `react@16.8.0` or greater which includes hooks.\n\n## Installation\n\nThis package is distributed via [npm](https://www.npmjs.com/package/@wellyshen/use-web-animations).\n\n```sh\n$ yarn add @wellyshen/use-web-animations\n# or\n$ npm install --save @wellyshen/use-web-animations\n```\n\n## Before We Start\n\nWith the Web Animations API, we can move interactive animations from stylesheets to JavaScript, separating presentation from behavior. The API was designed based on the concept of the [CSS Animations](https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_Animations/Using_CSS_animations) but there're still some differences between them. I strongly recommend you to read the [documentation](https://developer.mozilla.org/en-US/docs/Web/API/Web_Animations_API/Using_the_Web_Animations_API) before we dive into this hook.\n\n## Usage\n\nThe [API](#api) design of the hook not only inherits the DX of the [Web Animations API](https://developer.mozilla.org/en-US/docs/Web/API/Web_Animations_API) but also provides useful features and sugar events to us. Here are some examples to show you how does it work.\n\n\u003e ⚠️ [Most modern browsers support Web Animations API natively](https://caniuse.com/web-animation). You can also use [polyfill](#use-polyfill) for full browser support.\n\n### Basic Usage\n\nCreate an animation by the `keyframes` and `animationOptions` options (these are the [parameters](https://developer.mozilla.org/en-US/docs/Web/API/Element/animate#parameters) of the `Element.animate()`).\n\n\u003e 💡 This hook supports the [pseudoElement](https://css-tricks.com/pseudo-elements-in-the-web-animations-api/) property via the `animationOptions` option.\n\n[![Edit useWebAnimations - basic](https://codesandbox.io/static/img/play-codesandbox.svg)](https://codesandbox.io/s/usewebanimations-basic-nf0kd?fontsize=14\u0026hidenavigation=1\u0026theme=dark)\n\n```js\nimport useWebAnimations from \"@wellyshen/use-web-animations\";\n\nconst App = () =\u003e {\n  const { ref, playState } = useWebAnimations({\n    keyframes: {\n      transform: \"translateX(500px)\", // Move by 500px\n      background: [\"red\", \"blue\", \"green\"], // Go through three colors\n    },\n    animationOptions: {\n      delay: 500, // Start with a 500ms delay\n      duration: 1000, // Run for 1000ms\n      iterations: 2, // Repeat once\n      direction: \"alternate\", // Run the animation forwards and then backwards\n      easing: \"ease-in-out\", // Use a fancy timing function\n    },\n    onReady: ({ playState, animate, animation }) =\u003e {\n      // Triggered when the animation is ready to play\n    },\n    onUpdate: ({ playState, animate, animation }) =\u003e {\n      // Triggered when the animation enters the running state or changes state\n    },\n    onFinish: ({ playState, animate, animation }) =\u003e {\n      // Triggered when the animation enters the finished state\n    },\n    // More useful options...\n  });\n\n  return (\n    \u003cdiv className=\"container\"\u003e\n      \u003cp\u003e🍿 Animation is {playState}\u003c/p\u003e\n      \u003cdiv className=\"target\" ref={ref} /\u003e\n    \u003c/div\u003e\n  );\n};\n```\n\nFor browsers that don't yet support the `onReady` and `onFinish` events, we can use the `onUpdate` to monitor the animation's state instead.\n\n```js\nlet prevPending = true;\n\nconst App = () =\u003e {\n  const { ref } = useWebAnimations({\n    // ...\n    onUpdate: ({ playState, animation: { pending } }) =\u003e {\n      if (prevPending \u0026\u0026 !pending) {\n        console.log(\"Animation is ready to play\");\n      }\n      prevPending = pending;\n\n      if (playState === \"finished\") {\n        console.log(\"Animation has finished playing\");\n      }\n    },\n  });\n\n  // ...\n};\n```\n\n### Setting/Updating Animation\n\nThe `keyframes` and `animationOptions` are cached when the hook is mounted. However, we can set/update the animation by the `animation` method.\n\n```js\nconst { animation } = useWebAnimations();\n\nconst changeAnim = () =\u003e\n  animation({\n    keyframes: { transform: [\"translateX(0)\", \"translateX(100px)\"] },\n    animationOptions: 1000,\n    id: \"123\",\n    playbackRate: 1,\n    autoPlay: true,\n  });\n```\n\n### Playback Control\n\nThe shortcoming with existing technologies was the lack of playback control. The Web Animations API provides several useful methods for controlling playback: play, pause, reverse, cancel, finish, seek, control speed via the [methods](https://developer.mozilla.org/en-US/docs/Web/API/Animation#Methods) of the **Animation** interface. This hook exposes the animation instance for us to interact with animations, we can access it by the `getAnimation()` return value.\n\n[![Edit useWebAnimations - controls](https://codesandbox.io/static/img/play-codesandbox.svg)](https://codesandbox.io/s/usewebanimations-controls-hst8v?fontsize=14\u0026hidenavigation=1\u0026theme=dark)\n\n```js\nimport useWebAnimations from \"@wellyshen/use-web-animations\";\n\nconst App = () =\u003e {\n  const { ref, playState, getAnimation } = useWebAnimations({\n    playbackRate: 0.5, // Change playback rate, default is 1\n    autoPlay: false, // Automatically starts the animation, default is true\n    keyframes: { transform: \"translateX(500px)\" },\n    animationOptions: { duration: 1000, fill: \"forwards\" },\n  });\n\n  const play = () =\u003e {\n    getAnimation().play();\n  };\n\n  const pause = () =\u003e {\n    getAnimation().pause();\n  };\n\n  const reverse = () =\u003e {\n    getAnimation().reverse();\n  };\n\n  const cancel = () =\u003e {\n    getAnimation().cancel();\n  };\n\n  const finish = () =\u003e {\n    getAnimation().finish();\n  };\n\n  const seek = (e) =\u003e {\n    const animation = getAnimation();\n    const time = (animation.effect.getTiming().duration / 100) * e.target.value;\n    animation.currentTime = time;\n  };\n\n  const updatePlaybackRate = (e) =\u003e {\n    getAnimation().updatePlaybackRate(e.target.value);\n  };\n\n  return (\n    \u003cdiv className=\"container\"\u003e\n      \u003cbutton onClick={play}\u003ePlay\u003c/button\u003e\n      \u003cbutton onClick={pause}\u003ePause\u003c/button\u003e\n      \u003cbutton onClick={reverse}\u003eReverse\u003c/button\u003e\n      \u003cbutton onClick={cancel}\u003eCancel\u003c/button\u003e\n      \u003cbutton onClick={finish}\u003eFinish\u003c/button\u003e\n      \u003cinput type=\"range\" onChange={seek} /\u003e\n      \u003cinput type=\"number\" defaultValue=\"1\" onChange={updatePlaybackRate} /\u003e\n      \u003cdiv className=\"target\" ref={ref} /\u003e\n    \u003c/div\u003e\n  );\n};\n```\n\n### Getting Animation's Information\n\nWhen using the Web Animations API, we can get the information of an animation via the [properties](https://developer.mozilla.org/en-US/docs/Web/API/Animation#Properties) of the **Animation** interface. However, we can get the information of an animation by the `getAnimation()` return value as well.\n\n```js\nimport useWebAnimations from \"@wellyshen/use-web-animations\";\n\nconst App = () =\u003e {\n  const { ref, getAnimation } = useWebAnimations({\n    keyframes: { transform: \"translateX(500px)\" },\n    animationOptions: { duration: 1000, fill: \"forwards\" },\n  });\n\n  const speedUp = () =\u003e {\n    const animation = getAnimation();\n    animation.updatePlaybackRate(animation.playbackRate * 0.25);\n  };\n\n  const jumpToHalf = () =\u003e {\n    const animation = getAnimation();\n    animation.currentTime = animation.effect.getTiming().duration / 2;\n  };\n\n  return (\n    \u003cdiv className=\"container\"\u003e\n      \u003cbutton onClick={speedUp}\u003eSpeed Up\u003c/button\u003e\n      \u003cbutton onClick={jumpToHalf}\u003eJump to Half\u003c/button\u003e\n      \u003cdiv className=\"target\" ref={ref} /\u003e\n    \u003c/div\u003e\n  );\n};\n```\n\nThe animation instance isn't a part of [React state](https://reactjs.org/docs/hooks-state.html), which means we need to access it by the `getAnimation()` whenever we need. If you want to monitor an animation's information, here's the `onUpdate` event for you. The event is implemented by the [requestAnimationFrame](https://developer.mozilla.org/en-US/docs/Web/API/window/requestAnimationFrame) internally and the event callback is triggered when the animation enters `running` state or changes state.\n\n```js\nimport { useState } from \"react\";\nimport useWebAnimations from \"@wellyshen/use-web-animations\";\n\nconst App = () =\u003e {\n  const [showEl, setShowEl] = useState(false);\n  const { ref } = useWebAnimations({\n    keyframes: { transform: \"translateX(500px)\" },\n    animationOptions: { duration: 1000, fill: \"forwards\" },\n    onUpdate: ({ animation }) =\u003e {\n      if (animation.currentTime \u003e animation.effect.getTiming().duration / 2)\n        setShowEl(true);\n    },\n  });\n\n  return (\n    \u003cdiv className=\"container\"\u003e\n      {showEl \u0026\u0026 \u003cdiv className=\"some-element\" /\u003e}\n      \u003cdiv className=\"target\" ref={ref} /\u003e\n    \u003c/div\u003e\n  );\n};\n```\n\n### Dynamic Interactions with Animation\n\nWe can create and play an animation at the `animationOptions` we want by the `animate` method, which is implemented based on the [Element.animate()](https://developer.mozilla.org/en-US/docs/Web/API/Element/animate). It's useful for interactions and the [composite modes](https://css-tricks.com/additive-animation-web-animations-api).\n\nLet's create a mouse interaction effect:\n\n[![Edit useWebAnimations - interaction](https://codesandbox.io/static/img/play-codesandbox.svg)](https://codesandbox.io/s/usewebanimations-interaction-4jrs9?fontsize=14\u0026hidenavigation=1\u0026theme=dark)\n\n```js\nimport { useEffect } from \"react\";\nimport useWebAnimations from \"@wellyshen/use-web-animations\";\n\nconst App = () =\u003e {\n  const { ref, animate } = useWebAnimations();\n\n  useEffect(() =\u003e {\n    document.addEventListener(\"mousemove\", (e) =\u003e {\n      // The target will follow the mouse cursor\n      animate({\n        keyframes: { transform: `translate(${e.clientX}px, ${e.clientY}px)` },\n        animationOptions: { duration: 500, fill: \"forwards\" },\n      });\n    });\n  }, [animate]);\n\n  return (\n    \u003cdiv className=\"container\"\u003e\n      \u003cdiv className=\"target\" ref={ref} /\u003e\n    \u003c/div\u003e\n  );\n};\n```\n\nCreate a bounce effect via lifecycle and composite mode:\n\n```js\nimport useWebAnimations from \"@wellyshen/use-web-animations\";\n\nconst App = () =\u003e {\n  const { ref, animate } = useWebAnimations({\n    id: \"fall\", // Set animation id, default is empty string\n    keyframes: [{ top: 0, easing: \"ease-in\" }, { top: \"500px\" }],\n    animationOptions: { duration: 300, fill: \"forwards\" },\n    onFinish: ({ animate, animation }) =\u003e {\n      // Lifecycle is triggered by each animation, we can check the id to prevent animation from repeating\n      if (animation.id === \"bounce\") return;\n\n      animate({\n        id: \"bounce\",\n        keyframes: [\n          { top: \"500px\", easing: \"ease-in\" },\n          { top: \"10px\", easing: \"ease-out\" },\n        ],\n        animationOptions: { duration: 300, composite: \"add\" },\n      });\n    },\n  });\n\n  return (\n    \u003cdiv className=\"container\"\u003e\n      \u003cdiv className=\"target\" ref={ref} /\u003e\n    \u003c/div\u003e\n  );\n};\n```\n\n\u003e ⚠️ Composite modes isn't fully supported by all the browsers, please check the [browser compatibility](https://developer.mozilla.org/en-US/docs/Web/API/KeyframeEffect/composite#Browser_compatibility) carefully before using it.\n\n## Use Built-in Animations\n\nToo lazy to think about animation? We provide a collection of ready-to-use animations for you, they are implemented based on [Animate.css](https://animate.style).\n\n👉🏻 [Check out the demo](https://use-web-animations.netlify.app#animations).\n\n```js\nimport useWebAnimations, { bounce } from \"@wellyshen/use-web-animations\";\n\nconst App = () =\u003e {\n  // Add a pre-defined effect to the target\n  const { ref } = useWebAnimations({ ...bounce });\n\n  return (\n    \u003cdiv className=\"container\"\u003e\n      \u003cdiv className=\"target\" ref={ref} /\u003e\n    \u003c/div\u003e\n  );\n};\n```\n\nWe can customize the built-in animation by overriding its properties:\n\n```js\nconst { keyframes, animationOptions } = bounce;\nconst { ref } = useWebAnimations({\n  keyframes,\n  animationOptions: {\n    ...animationOptions,\n    delay: 1000, // Delay 1s\n    duration: animationOptions.duration * 0.75, // Speed up the animation\n  },\n});\n```\n\n\u003cdetails\u003e\n\u003csummary\u003eSee all available animations\u003c/summary\u003e\n\n#### Attention seekers\n\n- bounce\n- flash\n- pulse\n- rubberBand\n- shakeX\n- shakeY\n- headShake\n- swing\n- tada\n- wobble\n- jello\n- heartBeat\n\n#### Back entrances\n\n- backInDown\n- backInLeft\n- backInRight\n- backInUp\n\n#### Back exits\n\n- backOutDown\n- backOutLeft\n- backOutRight\n- backOutUp\n\n#### Bouncing entrances\n\n- bounceIn\n- bounceInDown\n- bounceInLeft\n- bounceInRight\n- bounceInUp\n\n#### Bouncing exits\n\n- bounceOut\n- bounceOutDown\n- bounceOutLeft\n- bounceOutRight\n- bounceOutUp\n\n#### Fading entrances\n\n- fadeIn\n- fadeInDown\n- fadeInDownBig\n- fadeInLeft\n- fadeInLeftBig\n- fadeInRight\n- fadeInRightBig\n- fadeInUp\n- fadeInUpBig\n- fadeInTopLeft\n- fadeInTopRight\n- fadeInBottomLeft\n- fadeInBottomRight\n\n#### Fading exits\n\n- fadeOut\n- fadeOutDown\n- fadeOutDownBig\n- fadeOutLeft\n- fadeOutLeftBig\n- fadeOutRight\n- fadeOutRightBig\n- fadeOutUp\n- fadeOutUpBig\n- fadeOutTopLeft\n- fadeOutTopRight\n- fadeOutBottomLeft\n- fadeOutBottomRight\n\n#### Flippers\n\n- flip\n- flipInX\n- flipInY\n- flipOutX\n- flipOutY\n\n#### Lightspeed\n\n- lightSpeedInRight\n- lightSpeedInLeft\n- lightSpeedOutRight\n- lightSpeedOutLeft\n\n#### Rotating entrances\n\n- rotateIn\n- rotateInDownLeft\n- rotateInDownRight\n- rotateInUpLeft\n- rotateInUpRight\n\n#### Rotating exits\n\n- rotateOut\n- rotateOutDownLeft\n- rotateOutDownRight\n- rotateOutUpLeft\n- rotateOutUpRight\n\n#### Specials\n\n- hinge\n- jackInTheBox\n- rollIn\n- rollOut\n\n#### Zooming entrances\n\n- zoomIn\n- zoomInDown\n- zoomInLeft\n- zoomInRight\n- zoomInUp\n\n#### Zooming exits\n\n- zoomOut\n- zoomOutDown\n- zoomOutLeft\n- zoomOutRight\n- zoomOutUp\n\n#### Sliding entrances\n\n- slideInDown\n- slideInLeft\n- slideInRight\n- slideInUp\n\n#### Sliding exits\n\n- slideOutDown\n- slideOutLeft\n- slideOutRight\n- slideOutUp\n\u003c/details\u003e\n\n## Use Your Own `ref`\n\nIn case of you had a ref already or you want to share a ref for other purposes. You can pass in the ref instead of using the one provided by this hook.\n\n```js\nconst ref = useRef();\nconst { playState } = useWebAnimations({ ref });\n```\n\n## Working in TypeScript\n\nThis hook supports [TypeScript](https://www.typescriptlang.org), you can tell the hook what type of element you are going to animate through the [generic type](https://www.typescriptlang.org/docs/handbook/generics.html):\n\n```ts\nconst App = () =\u003e {\n  const { ref } = useWebAnimations\u003cHTMLDivElement\u003e();\n\n  return \u003cdiv ref={ref} /\u003e;\n};\n```\n\n\u003e 💡 For more available types, please [check it out](src/use-web-animations.d.ts).\n\n## API\n\n```js\nconst returnObj = useWebAnimations(options?: object);\n```\n\n### Return Object\n\nIt's returned with the following properties.\n\n| Key            | Type                | Default | Description                                                                                                                                                                                                 |\n| -------------- | ------------------- | ------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| `ref`          | object              |         | Used to set the target element for animating.                                                                                                                                                               |\n| `playState`    | string \\| undefined |         | Describes the [playback state](https://developer.mozilla.org/en-US/docs/Web/API/Animation/playState#value) of an animation.                                                                                 |\n| `getAnimation` | function            |         | Access the [animation instance](https://developer.mozilla.org/en-US/docs/Web/API/Animation) for [playback control](#playback-control), [animation's information](#getting-animations-information) and more. |\n| `animate`      | function            |         | Imperatively [set/update the animation](#settingupdating-animation). Useful for [interactive animations and composite animations](#dynamic-interactions-with-animation).                                    |\n\n### Parameter\n\nThe `options` provides the following configurations and event callbacks for you.\n\n| Key                | Type             | Default | Description                                                                                                                                                                          |\n| ------------------ | ---------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |\n| `ref`              | object           |         | For [some reasons](#use-your-own-ref), you can pass in your own ref instead of using the built-in.                                                                                   |\n| `id`               | string           | `\"\"`    | Sets the ID of an animation, implemented based on the [Animation.id](https://developer.mozilla.org/en-US/docs/Web/API/Animation/id).                                                 |\n| `playbackRate`     | number           | `1`     | Sets the playback rate of an animation, implemented based on the [Animation.playbackRate](https://developer.mozilla.org/en-US/docs/Web/API/Animation/playbackRate).                  |\n| `autoPlay`         | boolean          | `true`  | Automatically starts the animation.                                                                                                                                                  |\n| `keyframes`        | Array \\| object  |         | An array of keyframe objects, or a keyframe object whose property are arrays of values to iterate over. See [basic usage](#basic-usage) for more details.                            |\n| `animationOptions` | number \\| object |         | An **integer** representing the animation's duration (in milliseconds), or an **object** containing one or more timing properties. See [basic usage](#basic-usage) for more details. |\n| `onReady` | function | | It's invoked when an animation is ready to play. You can access the [playState](#basic-usage), [animate](#dynamic-interactions-with-animation) and [animation](#getting-animations-information) from the event object. |\n| `onUpdate` | function | | It's invoked when an animation enters the `running` state or changes state. You can access the [playState](#basic-usage), [animate](#dynamic-interactions-with-animation) and [animation](#getting-animations-information) from the event object. |\n| `onFinish` | function | | It's invoked when an animation enters the `finished` state. You can access the [playState](#basic-usage), [animate](#dynamic-interactions-with-animation) and [animation](#getting-animations-information) from the event object. |\n\n## Use Polyfill\n\n[Web Animations API has good support amongst browsers](https://caniuse.com/web-animation), but it's not universal. You'll need to polyfill browsers that don't support it. Polyfills is something you should do consciously at the application level. Therefore `use-web-animations` doesn't include it.\n\nInstall [web-animations-js](https://github.com/web-animations/web-animations-js):\n\n```sh\n$ yarn add web-animations-js\n# or\n$ npm install --save web-animations-js\n```\n\nThen import it at your app's entry point:\n\n```js\nimport \"web-animations-js/web-animations.min\";\n```\n\nYou can read the [document](https://github.com/web-animations/web-animations-js/blob/dev/docs/support.md) for more information.\n\n## Articles / Blog Posts\n\n\u003e 💡 If you have written any blog post or article about `use-web-animations`, please open a PR to add it here.\n\n- Featured on [React Status #196](https://react.statuscode.com/issues/196).\n- Featured on [JavaScript Weekly #496](https://javascriptweekly.com/issues/496).\n- Featured on [React Newsletter #218](https://reactnewsletter.com/issues/218).\n\n## Contributors ✨\n\nThanks goes to these wonderful people ([emoji key](https://allcontributors.org/docs/en/emoji-key)):\n\n\u003c!-- ALL-CONTRIBUTORS-LIST:START - Do not remove or modify this section --\u003e\n\u003c!-- prettier-ignore-start --\u003e\n\u003c!-- markdownlint-disable --\u003e\n\u003ctable\u003e\n  \u003ctr\u003e\n    \u003ctd align=\"center\"\u003e\u003ca href=\"https://wellyshen.com\"\u003e\u003cimg src=\"https://avatars1.githubusercontent.com/u/21308003?v=4\" width=\"100px;\" alt=\"\"/\u003e\u003cbr /\u003e\u003csub\u003e\u003cb\u003eWelly\u003c/b\u003e\u003c/sub\u003e\u003c/a\u003e\u003cbr /\u003e\u003ca href=\"https://github.com/wellyshen/use-web-animations/commits?author=wellyshen\" title=\"Code\"\u003e💻\u003c/a\u003e \u003ca href=\"https://github.com/wellyshen/use-web-animations/commits?author=wellyshen\" title=\"Documentation\"\u003e📖\u003c/a\u003e \u003ca href=\"#maintenance-wellyshen\" title=\"Maintenance\"\u003e🚧\u003c/a\u003e\u003c/td\u003e\n  \u003c/tr\u003e\n\u003c/table\u003e\n\n\u003c!-- markdownlint-enable --\u003e\n\u003c!-- prettier-ignore-end --\u003e\n\n\u003c!-- ALL-CONTRIBUTORS-LIST:END --\u003e\n\nThis project follows the [all-contributors](https://github.com/all-contributors/all-contributors) specification. Contributions of any kind welcome!\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fwellyshen%2Fuse-web-animations","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fwellyshen%2Fuse-web-animations","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fwellyshen%2Fuse-web-animations/lists"}