{"id":17350347,"url":"https://github.com/jlkiri/use-animate-presence","last_synced_at":"2025-04-14T10:21:58.003Z","repository":{"id":52574397,"uuid":"286232673","full_name":"jlkiri/use-animate-presence","owner":"jlkiri","description":"⚛️ A React hook for animating components when they are mounted and unmounted. Fast and tiny.","archived":false,"fork":false,"pushed_at":"2021-04-25T12:52:58.000Z","size":2505,"stargazers_count":73,"open_issues_count":1,"forks_count":3,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-03-27T23:33:02.829Z","etag":null,"topics":["animation","hook","react","transition"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/jlkiri.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2020-08-09T12:28:10.000Z","updated_at":"2024-11-02T15:39:18.000Z","dependencies_parsed_at":"2022-09-04T10:51:31.595Z","dependency_job_id":null,"html_url":"https://github.com/jlkiri/use-animate-presence","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jlkiri%2Fuse-animate-presence","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jlkiri%2Fuse-animate-presence/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jlkiri%2Fuse-animate-presence/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jlkiri%2Fuse-animate-presence/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/jlkiri","download_url":"https://codeload.github.com/jlkiri/use-animate-presence/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248860053,"owners_count":21173352,"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","react","transition"],"created_at":"2024-10-15T17:06:36.074Z","updated_at":"2025-04-14T10:21:57.968Z","avatar_url":"https://github.com/jlkiri.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003ch1 align=\"center\"\u003e\u003cstrong\u003euse-animate-presence\u003c/strong\u003e\u003c/h1\u003e\n\u003cp align=\"center\"\u003e\u003cimg width=\"480\" height=\"240\" src=\"https://raw.githubusercontent.com/jlkiri/use-animate-presence/main/assets/use-animation-presence.gif\" /\u003e\u003c/p\u003e\n\u003cp align=\"center\" style=\"font-size: 18px\"\u003e\u003cstrong\u003eA React hook for animating components when they are mounted and unmounted (added to / removed from React tree).\u003c/strong\u003e\u003c/p\u003e\n\n# Features:\n\n- Uses Web Animation API (60fps animation off main thread)\n- Spring physics based animation\n- Cancelable / reversable animations\n- Chainable mounts / unmounts\n- Small (~1KB)\n\n# Demo\n\n[![Edit use-animate-presence-logo](https://codesandbox.io/static/img/play-codesandbox.svg)](https://codesandbox.io/s/use-animate-presence-logo-vxdqc?fontsize=14\u0026hidenavigation=1\u0026theme=dark)\n\n# Get started\n\n- NPM: `npm install use-animate-presence`\n- UMD: https://unpkg.com/use-animate-presence@latest/lib/use-animate-presence.umd.js\n\n# Basic usage\n\n```jsx\nimport { useAnimatePresence } from \"use-animate-presence\";\n\nconst variants = {\n  x: { from: -800, to: 0 },\n};\n\nexport default function App() {\n  const animatedDiv = useAnimatePresence({\n    variants,\n    initial: \"visible\",\n  });\n\n  return (\n    \u003cdiv\u003e\n      \u003cbutton onClick={() =\u003e animatedDiv.togglePresence()}\u003eToggle\u003c/button\u003e\n      {animatedDiv.isRendered \u0026\u0026 \u003cdiv ref={animatedDiv.ref} /\u003e}\n    \u003c/div\u003e\n  );\n}\n```\n\nPlay with the code here:\n\n[![Edit use-animate-presence-basic-demo](https://codesandbox.io/static/img/play-codesandbox.svg)](https://codesandbox.io/s/use-animate-presence-basic-demo-fpwy0?fontsize=14\u0026hidenavigation=1\u0026theme=dark)\n\n# Advanced usage\n\n`useAnimatePresence` takes one object as an argument. Below is a table with possible properties and their description (some properties are explained in detail later):\n\n|       Property       |   Default    | Required |          Type          |                                 Details                                 |\n| :------------------: | :----------: | :------: | :--------------------: | :---------------------------------------------------------------------: |\n|      `variants`      |      -       |  `true`  |        `object`        |                    Properties and values to animate                     |\n|      `initial`       |      -       |  `true`  | `\"hidden\" or \"visible\"` |                   Whether item is rendered initially                    |\n| `animateFirstRender` |    `true`    | `false`  |       `boolean`        |            Whether to animate on first render (first mount)             |\n|       `enter`        | `undefined`  | `false`  |       `function`       |          Function to execute when enter animation is finished           |\n|        `exit`        | `undefined`  | `false`  |       `function`       |           Function to execute when exit animation is finished           |\n|        `wait`        | `undefined`  | `false`  |       `function`       | Function to execute both when enter and when exit animation is finished |\n|     `debugName`      |     `\"\"`     | `false`  |        `string`        |          Name for tracking the animation lifecycle of the hook, if not provided it won't show logs to console          |\n|      `duration`      |    `1000`    | `false`  |        `number`        |        Animation duration (ms) (use if you only animate opacity)        |\n|      `options`       | (read below) | `false`  |        `object`        |           Spring options (stiffness, mass and damping ratio)            |\n\n## Return value\n\n`useAnimatePresence` returns an object which contains a function that can toggle presence, a ref that you need to attach to the element you want to animate and a `isRendered` property which you can use to conditionally render elements.\n\n|     Property     |                           Details                            |\n| :--------------: | :----------------------------------------------------------: |\n|      `ref`       |                         React `ref`                          |\n| `togglePresence` |        Function that toggles presence (and animates)         |\n|   `isRendered`   | Boolean that should be used to conditionally render elements |\n\nLook again at the example above to see how all properties are used:\n\n```javascript\nreturn (\n  \u003cdiv\u003e\n    \u003cbutton onClick={() =\u003e animatedDiv.togglePresence()}\u003eToggle\u003c/button\u003e\n    {animatedDiv.isRendered \u0026\u0026 \u003cdiv ref={animatedDiv.ref} /\u003e}\n  \u003c/div\u003e\n);\n```\n\n## Variants\n\nVariants look like this:\n\n```javascript\nconst variants = {\n  x: { from: -800, to: 0 },\n  deg: 360,\n};\n```\n\nExcept for `deg`, which is degrees of rotation, every property must have a `from` value and a `to` value. All possible properties are: `x`, `y`, `deg`, `opacity` and `scale` (`scale` is experimental and might not work as intended).\n\n## `enter`, `exit` and `wait`\n\nThese are callbacks to be executed after `enter` (mount) or `exit` (unmount) animation finishes. `wait` is simply a shorthand - if you need to execute the same callback on both `enter` and `exit` animations you can just pass it as a `wait` property. Mostly, you will need this to chain mounts / unmounts. For example, if you want element B to animate only after element A is finished, you can do this:\n\n```javascript\nconst elementA = useAnimatePresence({\n  variants: springVariants,\n  initial: \"hidden\",\n  debugName: \"front-square\",\n});\n\nconst elementB = useAnimatePresence({\n  variants: springVariants,\n  initial: \"visible\",\n  wait: elementA.togglePresence,\n});\n\nreturn (\n  \u003c\u003e\n    {\u003cbutton onClick={() =\u003e elementB.togglePresence()}\u003eToggle\u003c/button\u003e}\n    {elementB.isRendered \u0026\u0026 (\n      \u003cdiv ref={elementB.ref}\u003e\n        {elementA.isRendered \u0026\u0026 \u003cdiv ref={elementA.ref} /\u003e}\n      \u003c/div\u003e\n    )}\n  \u003c/\u003e\n);\n```\n\nIn this example, `elementA` will not be animated and its property `isRendered` will be false until `elementB` is finished animating. Play with a complex example here:\n\n[![Edit use-animate-presence-demo](https://codesandbox.io/static/img/play-codesandbox.svg)](https://codesandbox.io/s/use-animate-presence-demo-cfn8b?fontsize=14\u0026hidenavigation=1\u0026theme=dark)\n\n## Spring options\n\nSprings have stiffness, mass and damping ratio. The defaults are: stiffness `150`, mass `3` and damping `27`. You can customize the parameters like this:\n\n```javascript\nuseAnimatePresence({\n  variants,\n  initial: \"visible\",\n  options: {\n    stiffness: 500,\n    mass: 1,\n    damping: 10,\n  },\n});\n```\n\n# Recipes\n\n## Toast notifications\n\nYou can easily create nice toast notifications with this library.\n\n\u003cp align=\"center\"\u003e\u003cimg src=\"./assets/smooth-popup.gif\" width=\"500\" height=\"300\" /\u003e\u003c/p\u003e\n\nCode:\n\n[![Edit animate-popup](https://codesandbox.io/static/img/play-codesandbox.svg)](https://codesandbox.io/s/animate-popup-ww83f?fontsize=14\u0026hidenavigation=1\u0026theme=dark)\n\n## Arbitrary number of animatable items\n\nYou can render an arbitrary array of items that are animatable with `useAnimatePresence`. Here is something you can achieve if you combine this library with [react-easy-flip](https://github.com/jlkiri/react-easy-flip).\n\n\u003cp align=\"center\"\u003e\u003cimg src=\"./assets/multiple-presence.gif\" width=\"300\" height=\"500\" /\u003e\u003c/p\u003e\n\nCode:\n\n[![Edit animate-presence-multiple-2](https://codesandbox.io/static/img/play-codesandbox.svg)](https://codesandbox.io/s/animate-presence-multiple-2-o804h?fontsize=14\u0026hidenavigation=1\u0026theme=dark)\n\n# Requirements\n\nThis library requires React version 16.8.0 or higher (the one with Hooks).\n\n# Contribution\n\nAny kind of contribution is welcome!\n\n1. Open an issue or pick an existing one that you want to work on\n2. Fork this repository\n3. Clone your fork to work on it locally\n4. Make changes\n5. Run `yarn build` and make sure that it builds without crash\n6. Push changes and [open a pull request](https://docs.github.com/en/github/collaborating-with-issues-and-pull-requests/creating-a-pull-request)\n\nNote: if you want to link the package to some other project to do integration tests, you may run into an issue with two React versions. In this case, run `npm link \u003cpath-to-react-in-your-other-project\u003e` while in `use-animation-presence` root directory.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjlkiri%2Fuse-animate-presence","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjlkiri%2Fuse-animate-presence","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjlkiri%2Fuse-animate-presence/lists"}