{"id":13451956,"url":"https://github.com/vincentriemer/addimated","last_synced_at":"2025-04-12T10:42:52.133Z","repository":{"id":34048606,"uuid":"167076979","full_name":"vincentriemer/addimated","owner":"vincentriemer","description":"An always interruptible, declarative animation library for React.","archived":false,"fork":false,"pushed_at":"2023-01-04T02:42:11.000Z","size":4795,"stargazers_count":108,"open_issues_count":46,"forks_count":2,"subscribers_count":4,"default_branch":"develop","last_synced_at":"2025-04-09T16:06:55.922Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"https://github.com/vincentriemer/addimated","language":"JavaScript","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/vincentriemer.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.md","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2019-01-22T22:26:54.000Z","updated_at":"2023-08-22T17:33:53.000Z","dependencies_parsed_at":"2023-01-15T04:15:17.899Z","dependency_job_id":null,"html_url":"https://github.com/vincentriemer/addimated","commit_stats":null,"previous_names":[],"tags_count":6,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vincentriemer%2Faddimated","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vincentriemer%2Faddimated/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vincentriemer%2Faddimated/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vincentriemer%2Faddimated/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/vincentriemer","download_url":"https://codeload.github.com/vincentriemer/addimated/tar.gz/refs/heads/develop","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248196641,"owners_count":21063472,"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":[],"created_at":"2024-07-31T07:01:08.290Z","updated_at":"2025-04-12T10:42:52.109Z","avatar_url":"https://github.com/vincentriemer.png","language":"JavaScript","funding_links":[],"categories":["JavaScript"],"sub_categories":[],"readme":"\u003ch1 align=\"center\"\u003e\n  addimated\n\u003c/h1\u003e\n\n\u003cp align=\"center\"\u003eAn always interruptible, declarative animation library for React.\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003cimg alt=\"\" src=\"https://img.shields.io/badge/status-proof--of--concept-red.svg\" /\u003e\n  \u003ca href=\"https://www.npmjs.com/package/@unstable/addimated\"\u003e\n    \u003cimg alt=\"\" src=\"https://img.shields.io/npm/v/@unstable/addimated.svg\" /\u003e\n  \u003c/a\u003e\n  \u003ca href=\"https://bundlephobia.com/result?p=@unstable/addimated\"\u003e\n    \u003cimg alt=\"\" src=\"https://img.shields.io/bundlephobia/minzip/@unstable/addimated.svg\" /\u003e\n  \u003c/a\u003e\n\u003c/p\u003e\n\n\u003cbr /\u003e\n\n\u003ch2\u003e\n  WARNING\n\u003c/h2\u003e\n\nThis project is largely a proof-of-concept/experiment as a stepping stone to future animation work I have planned. Feel free to fool around with this but I wouldn't recommend using it in production. To wit, this library uses React hooks in its core so it depends on the unstable React version `16.8.0-alpha.1`.\n\n## Installation\n\n```sh\n# use npm\nnpm install @unstable/addimated\n\n# use yarn\nyarn add @unstable/addimated\n```\n\n## Usage\n\n```js\nimport * as Animated from \"@unstable/addimated\";\n```\n\nAddimated's API and usage largly mirror's React Native's [Animated](https://facebook.github.io/react-native/docs/animated) with a few notable changes:\n\n- Addimated exports a namespace instead of a default object export\n- When creating new animated values, instead of constructing classes like `new Animated.Value()` or `new Animated.ValueXY()`, you call the factory functions `Animated.createAnimatedValue()` and `Animated.createAnimatedValueXY()`\n- `interpolate` is its own exported function instead of a method on an animated value. So instead of\n\n  ```js\n  value.interpolate({\n    inputRange: [0, 1],\n    outputRange: [-100, 100]\n  });\n  ```\n\n  you should use\n\n  ```js\n  Animated.interpolate(value, {\n    inputRange: [0, 1],\n    outputRange: [-100, 100]\n  });\n  ```\n\n- Since Addimated targets the web instead of React Native, instead of exporting `Animated.View`, `Animated.Image`, ect. it exports [animated components suitable for the web](#built-in-animated-components).\n- Addimated provides hooks for a better development experience in React functional components. See [useAnimatedValue](#useanimatedvaluecurrentvalue-number-animationfactory-function-animatedvalue-boolean) for usage.\n\n## Examples\n\n- [Timing Sequence Overlap](https://codesandbox.io/embed/50wx3l4n6x?view=preview)\n- [Spring/Timing Interruption](https://codesandbox.io/embed/4xy742lvk7?view=preview)\n- [With `react-with-gesture`](https://codesandbox.io/embed/wo1vnm11pl?view=preview)\n\n## API Reference\n\n### Animated Values\n\n#### `createAnimatedValue(initialValue: number):`[`AnimatedValue`](#animatedvalue)\n\nCreates a standard value for driving animations.\n\n#### `createAnimatedValueXY(initialValueXY: { x: number, y: number }):`[`AnimatedValueXY`](#animatedvaluexy)\n\nCreates a 2D value for driving 2D animations, such as pan gestures.\n\n### Interpolation\n\n#### `interpolate(value:`[`AnimatedValue`](#animatedvalue)`, config: Object):`[`AnimatedValue`](#animatedvalue)\n\nMaps input ranges to output ranges, typically using a linear interpolation but also supports easing functions. By default, it will extrapolate the curve beyond the ranges given, but you can also have it clamp the output value.\n\nConfig is an object that may have the following options:\n\n- `inputRange`: _(required)_ An array of numbers (must be ascending) used to map against.\n- `outputRange`: _(required)_ An array of numbers (or strings for colors or values with units) to map to.\n- `easing`: an easing function to use instead of the default linear interpolation.\n- `extrapolate`: By default, `interpolate` will extrapolate values outside the input/output range with `\"extend\"`, but you can restrict the values by providing `\"clamp\"`.\n- `extrapolateLeft`: Same as `extrapolate` but only for the left side of the interpolation.\n- `extrapolateRight`: Same as `extrapolate` but only for the right side of the interpolation.\n\n### Animations\n\n#### `timing(value:`[`AnimatedValue`](#animatedvalue)`|`[`AnimatedValueXY`](#animatedvaluexy)`, config: Object):` [`Animation`](#animation)\n\nAnimates a value along a timed easing curve. The Easing module has tons of predefined curves, or you can use your own function.\n\nConfig is an object that may have the following options:\n\n- `toValue`: _(required)_ Next value to animate to\n- `duration`: Length of animation (milliseconds). Default 500.\n- `easing`: Easing function to define curve. Default is `Easing.inOut(Easing.ease)`.\n- `delay`: Start the animation after delay (milliseconds). Default 0.\n\n#### `spring(value:`[`AnimatedValue`](#animatedvalue)`|`[`AnimatedValueXY`](#animatedvaluexy)`, config: Object):`[`Animation`](#animation)\n\nAnimates a value according to an analytical spring model based on damped harmonic oscillation. Tracks velocity state to create fluid motions as the toValue updates, and can be chained together.\n\nConfig is an object that may have the following options.\n\nNote that you can only define one of bounciness/speed, tension/friction, or stiffness/damping/mass, but not more than one:\n\nThe friction/tension or bounciness/speed options match the spring model in Facebook Pop, Rebound, and Origami.\n\n- `friction`: Controls \"bounciness\"/overshoot. Default 7.\n- `tension`: Controls speed. Default 40.\n- `speed`: Controls speed of the animation. Default 12.\n- `bounciness`: Controls bounciness. Default 8.\n\nSpecifying stiffness/damping/mass as parameters makes Animated.spring use an analytical spring model based on the motion equations of a damped harmonic oscillator. This behavior is slightly more precise and faithful to the physics behind spring dynamics, and closely mimics the implementation in iOS's CASpringAnimation primitive.\n\n- `stiffness`: The spring stiffness coefficient. Default 100.\n- `damping`: Defines how the spring’s motion should be damped due to the forces of friction. Default 10.\n- `mass`: The mass of the object attached to the end of the spring. Default 1.\n\nOther configuration options are as follows:\n\n- `toValue`: _(required)_ Next value to animate to\n- `velocity`: The initial velocity of the object attached to the spring. Default 0 (object is at rest).\n- `overshootClamping`: Boolean indicating whether the spring should be clamped and not bounce. Default false.\n- `restDisplacementThreshold`: The threshold of displacement from rest below which the spring should be considered at rest. Default 0.001.\n- `restSpeedThreshold`: The speed at which the spring should be considered at rest in pixels per second. Default 0.001.\n- `delay`: Start the animation after delay (milliseconds). Default 0.\n\n### Composite Animations\n\n#### `delay(time: number):` [`Animation`](#animation)\n\nCreates an empty animation that lasts for the given `time`, useful when used inside a `sequence` to create spacing between animations.\n\n#### `sequence(animations:`[`Animation`](#animation)`[]):`[`Animation`](#animation)\n\nStarts an array of animations in order, waiting for each to complete before starting the next. If the current running animation is stopped, no following animations will be started.\n\n#### `parallel(animations:`[`Animation`](#animation)`[]):`[`Animation`](#animation)\n\nStarts an array of animations all at the same time.\n\n#### `stagger(time: number, animations:`[`Animation`](#animation)`[]):`[`Animation`](#animation)\n\nArray of animations may run in parallel (overlap), but are started in sequence with successive delays. Nice for doing trailing effects.\n\n### Animated Components\n\n#### `createAnimatedComponent(component: React.Component|string): AnimatedComponent`\n\nMake any React component Animatable. Used to create `Animated.div`, etc.\n\n#### Built-in Animated Components\n\n- `a`\n- `button`\n- `div`\n- `img`\n- `span`\n\n### Hooks\n\n#### `useAnimatedValue(currentValue: number, animationFactory: ?Function): [`[`AnimatedValue`](#animatedvalue)`, boolean]`\n\nA hook that turns the `currentValue` into an [`AnimatedValue`](#animatedvalue) where when the `currentValue` changes, it is animated with the [`Animation`](#animation) provided by the optional `animationFactory`.\n\nIf `animationFactory` is not provided it defaults to:\n\n```js\nfunction defaultAnimationFactory(animatedValue, toValue) {\n  return timing(animatedValue, { toValue });\n}\n```\n\nIt returns a tuple where the first value is the resulting [`AnimatedValue`](#animatedvalue) and the second is a `boolean` that specifies if the value is being animated or not.\n\n#### `useAnimatedValueXY(currentValue: { x: number, y: number }, animationFactory: ?Function): [`[`AnimatedValueXY`](#animatedvaluexy)`, boolean]`\n\nAn equivalent hook to `useAnimatedValue` but handles [`AnimatedXY`](#animatedxy) values instead\n\n### Easing\n\n#### Predefined Animations\n\n- `Easing.ease`: A simple inertial interaction, similar to an object slowly accelerating to speed.\n- `Easing.bounce`: Provides a simple bouncing effect.\n- `Easing.back(s)`: Use with `parallel()` to create a simple effect where the object animates back slightly as the animation starts.\n- `Easing.elastic(bounciness)`: A simple elastic interaction, similar to a spring oscillating back and forth.\n- `Easing.bezier(x1, y1, x2, y2)`: Provides a cubic bezier curve, equivalent to CSS Transitions' `transition-timing-function`.\n\n#### Standard Functions\n\n- `Easing.linear`: A linear function, `f(t) = t`. Position correlates to elapsed time one to one.\n- `Easing.quad`: A quadratic function, `f(t) = t * t`. Position equals the square of elapsed time.\n- `Easing.cubic`: A cubic function, `f(t) = t * t * t`. Position equals the cube of elapsed time.\n- `Easing.poly`: A power function. Position is equal to the Nth power of elapsed time.\n\n#### Modifiers\n\n- `Easing.in(easing)`: Runs an easing function forwards.\n- `Easing.out(easing)`: Runs an easing function backwards.\n- `Easing.inOut(easing)`: Makes any easing function symmetrical. The easing function will run forwards for half of the duration, then backwards for the rest of the duration.\n\n#### Additional Functions\n\n- `Easing.sin`: A sinusoidal function.\n- `Easing.circle`: A circular function.\n- `Easing.exp`: An exponential function.\n- `Easing.step0`: A stepping function, returns 1 for any positive value.\n- `Easing.step1`A stepping function, returns 1 if a value is greater than or equal to 1.\n\n### Interfaces\n\n#### AnimatedValue\n\n##### Methods\n\n- `setValue(value: number): void`\n- `setOffset(offset: number): void`\n- `flattenOffset(): void`\n- `extractOffset(): void`\n- `stopAnimations(callback: ?(value: number) =\u003e void): void`\n\n#### AnimatedValueXY\n\n##### Properties\n\n- `x:`[`AnimatedValue`](#animatedvalue)\n- `y:`[`AnimatedValue`](#animatedvalue)\n\n##### Methods\n\n- `setValue(value: { x: number, y: number }): void`\n- `setOffset(offset: { x: number, y: number }): void`\n- `flattenOffset(): void`\n- `extractOffset(): void`\n- `stopAnimations(callback: ?(value: { x: number, y: number }) =\u003e void): void`\n- `getTranslateTransform(): [{ translateX: number }, { translateY: number}]`\n\n#### Animation\n\n##### Methods\n\n- `start(callback: ?({ isFinished: boolean}) =\u003e void): void`\n\n## Development\n\nTo do a local build of Addimated: clone the respository, pull the package's depedencies, and run the project's build script like so:\n\n```sh\n# clone repo\ngit clone https://github.com/vincentriemer/addimated.git\ncd addimated\n\n# pull dependencies\nyarn install\n\n# run build script\nyarn run build\n```\n\nOnce you have done a local build, you can run the project's internal examples against it to test your changes by performing the following:\n\n```sh\n# assuming the current working directory is the root of the repo,\n# navigate to the examples folder\ncd examples\n\n# pull the example project's dependencies\nyarn install\n\n# start the development server\nyarn run start\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fvincentriemer%2Faddimated","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fvincentriemer%2Faddimated","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fvincentriemer%2Faddimated/lists"}