![](\"README/AnimateIn.gif\")
\r\n \r\n\r\n\r\n\r\n## ✅ List of Features \r\n\r\n- **Simple:** _No need to deal with **Animated.Values** to make great animations._\r\n- **Declarative:** _Describe your animations rather than build them._\r\n- **Powerful:** _Run multiple independent animations at once._\r\n- **Serializable:** _Schedule animations to follow one another._\r\n- **Smooth:** _Use **useNativeDriver** for extra performance._\r\n- **Type-Safe:** _Fully integrated with typescript out-of-the-box._\r\n\r\n\r\n\r\n## 🏁 Getting Started \r\n\r\n### **Prerequisites**\r\n\r\nWorks with any project implementing React 16.8 onwards\r\n\r\n\r\n\r\n### **Installing**\r\n\r\n```\r\nnpm i @huds0n/animations\r\n```\r\n\r\n\r\n\r\n## 🧑💻 Basic Usage \r\n\r\n### **Base Style**\r\n\r\nAnimated components style identically to their static counterpart. Updating _style_ will immediately change the appearance of a component.\r\n\r\n```jsx\r\nimport { AnimatedView } from \"@huds0n/animations\";\r\n\r\n// Inside component\r\n\r\n![](\"README/NoAnimation.gif\")
\r\n\r\n\r\n\r\n\r\n### **Basic Animation**\r\n\r\nPassing an [animationProps](#animation_props) into _animate_ will cause the component to transition to the new _style_. **Animated Components** will automatically detect and start animations on _animate_ change.\r\n\r\n```jsx\r\n![](\"README/fade.gif\")
\r\n\r\n_Note that animations will intelligently calculate style property start values even if it is already in mid animation!\r\n\r\nHowever, it's important not to mix numbered dimensions with string dimensions._\r\n\r\nIf no value is specified it assumes 0, '0%', '0deg', and 'transparent' for numbers, percentage dimensions, rotations, and colors respectively.\r\n\r\n\r\n\r\n### **Looping**\r\n\r\n_Loop_ can be added to an [animationProps](#animation_props) and can be easily controlled in three ways:\r\n\r\n- _boolean_ - permanent looping;\r\n- _number (multiples of 0.5)_ - select number of loops before stopping;\r\n- _ref ({ current: boolean })_ - detect and stops looping once set to false, e.g _loopRef.current = false_.\r\n\r\n```jsx\r\n// Loop ref\r\nconst loopRef = useRef(true)\r\n\r\n// Component\r\n![](\"README/loop.gif\")
\r\n\r\n\r\n\r\n\r\n### **Parallel Animations**\r\n\r\nMultiple animations can be started at once on a component. To do this simply pass the [animations](#animation_props) in as an _array_.\r\n\r\n```jsx\r\n![](\"README/parallel.gif\")
\r\n\r\n\r\n\r\n\r\n### **Sequence Animations**\r\n\r\nTo stack animations pass the following [animationProps](#animation_props) as a return value in the function _onAnimationEnd_.\r\n\r\n```jsx\r\n![](\"README/sequence.gif\")
\r\n\r\n\r\n\r\n\r\n## 🧑🔬 Advanced Usage \r\n\r\n### **Create Animated Component**\r\n\r\nAny component which has a style prop can be turned into an **animated component** using _createAnimatedComponent_.\r\n\r\n```jsx\r\nimport { Image } from \"react-native\";\r\nimport { createAnimatedComponent } from \"@huds0n/animations\";\r\n\r\nconst AnimatedImage = createAnimatedComponent(Image);\r\n```\r\n\r\n\r\n\r\n### **Use Native Driver**\r\n\r\nFor extra performance pass in the useNativeDriver prop. However, this can only work if you are animating native driver compatible props, such as _opacity_ and _transforms_.\r\n\r\n```jsx\r\n
\r\n\r\n### **Attach Animations**\r\n\r\nSometimes you may want to attach an animation to another **Animated.Value**, e.g. a _touch event_ created by **[PanResponder](https://reactnative.dev/docs/panresponder)**. By using the attach prop you set _styles_ at specific **Animated.Value** input points. The component will then animate fluidly between the input points.\r\n\r\n```jsx\r\n
![](\"README/attach.gif\")
\r\n\r\n_[See example for use case with PanResponder](#example)._\r\n\r\n\r\n\r\n## 📖 Reference \r\n\r\n### **Animation Props**\r\n\r\n| Prop | Required/_Default_ | Description | Type |\r\n| ---------------- | :----------------: | ------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------- |\r\n| to | ✔️ | Style to animate to | _textStyle_ or _viewStyle_ |\r\n| loop | _false_ | [See looping](#looping) | _boolean_, _number_, or _number ref_ |\r\n| onAnimationEnd | - | Called when animation endsPasses array of style props attached to animationAny _animationProp_ returned is ran in sequence | (attachedProps: _string array_) => _void_ or _animationProps_ |\r\n| onAnimationStart | - | Called when animation starts | () => _void_ |\r\n| type | _'TIMING'_ | Type of [animation method](https://reactnative.dev/docs/animated#methods) | _'TIMING'_, _'SPRING'_, or _'DECAY'_ |\r\n\r\n_All [Animation method](https://reactnative.dev/docs/animated#methods) specific props can also be used, such as **duration**, **velocity**, and **friction**._\r\n\r\n\r\n\r\n## 🎁 Extras \r\n\r\n### **ColorFader**\r\n\r\nContainer extending **React Native**'s **View** that smoothly animates background color.\r\n\r\n```jsx\r\n
![](\"README/transition.gif\"){kind=spacer}
\r\n\r\n\r\n\r\n### **Lists**\r\n\r\nAdds animation attached to flatlist scroll with automatic animate in.\r\n\r\n_Additional props:_\r\n\r\n| Prop | Required/_Default_ | Description | Type |\r\n| ----------------- | :----------------: | --------------------------------------------------------------------------------------------- | --------------------------------------------------------------- |\r\n| animationDelay | _0_ | Delay in ms on animating in | _number_ |\r\n| animationDuration | _2500_ | Duration in ms of animating in | _number_ |\r\n| at | - | Set styles at position points to animate between | _(**ElementPosition**) => [attachAtProp](#attach)_ |\r\n| itemLength | ✔️ | Length of _item element_ in direction of scroll | _number_ |\r\n| footerOffset | - | Footer offset | _number_ |\r\n| headerOffset | - | Header offset | _number_ |\r\n| ListComponent | _FlatList_ | List component to animate (will inherit props) | _React List Component_ |\r\n| offsetAnim | - | Scroll animated valueCan be attached to other Animated Components for complex animations | _Animated Value_ |\r\n| onAnimationEnd | - | Called when animation in complete | _() => void_ |\r\n| over | - | Set style function animate over | _(**ElementPosition**) => [attachOverProp](#attach)_ |\r\n| renderItem | ✔️ | Item render functionPassed **ElementPosition** with _ListRenderItemInfo_ | _(**ElementPosition** & ListRenderItemInfo) => React Component_ |\r\n| useNativeDriver | _false_ | Whether animation uses native driver | _boolean_ |\r\n\r\n\r\n\r\n_ElementPosition:_\r\n\r\n| Prop | Description | Type |\r\n| ----- | ----------------------------------------------------------------- | -------- |\r\n| index | Item index | _number_ |\r\n| row | Item row | _number_ |\r\n| start | Scroll offset at which the element is after the start of the view | _number_ |\r\n| end | Scroll offset at which the element is after the end of the view | _number_ |\r\n\r\n\r\n\r\n```jsx\r\n
\r\n\r\n## 📲 Example \r\n\r\nClone or fork the repo at [https://github.com/JontiHudson/modules-huds0n-animations](https://github.com/JontiHudson/modules-huds0n-animations)\r\n\r\nGo to the **\\_\\_example\\_\\_** folder. Run **npm install** to install the expo project, then **expo start** to launch the example.\r\n\r\n\r\n\r\n## ✍️ Authors \r\n\r\n- [@JontiHudson](https://github.com/JontiHudson) - Idea & Initial work\r\n- [@MartinHudson](https://github.com/martinhudson) - Support & Development\r\n\r\nSee also the list of [contributors](https://github.com/JontiHudson/modules-huds0n-shared-state/contributors) who participated in this project.\r\n\r\n\r\n\r\n## 🎉 Acknowledgements \r\n\r\n- Special thanks to my fiance, Arma, who has been so patient with all my extra-curricular work.\r\n","readmeFilename":"README.md"}