├── LICENSE.md ├── README.md ├── animateplus.js └── package.json /LICENSE.md: -------------------------------------------------------------------------------- 1 | The MIT License (MIT) 2 | 3 | Copyright (c) 2017-2018 Benjamin De Cock 4 | 5 | Permission is hereby granted, free of charge, to any person obtaining a copy 6 | of this software and associated documentation files (the "Software"), to deal 7 | in the Software without restriction, including without limitation the rights 8 | to use, copy, modify, merge, publish, distribute, sublicense, and/or sell 9 | copies of the Software, and to permit persons to whom the Software is 10 | furnished to do so, subject to the following conditions: 11 | 12 | The above copyright notice and this permission notice shall be included in all 13 | copies or substantial portions of the Software. 14 | 15 | THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR 16 | IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, 17 | FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE 18 | AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER 19 | LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, 20 | OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE 21 | SOFTWARE. 22 | -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- 1 | # Animate Plus 2 | 3 | Animate Plus is a JavaScript animation library focusing on performance and authoring flexibility. It 4 | aims to deliver a steady 60 FPS and weighs less than 3 KB (minified and compressed), making it particularly well-suited for mobile. 5 | 6 | ## Getting started 7 | 8 | `npm install animateplus` or download `animateplus.js` and start animating things: 9 | 10 | ```javascript 11 | import animate from "/animateplus.js"; 12 | 13 | animate({ 14 | elements: "div", 15 | duration: 2000, 16 | delay: index => index * 100, 17 | transform: ["scale(0)", "scale(1)"] 18 | }) 19 | .then(options => animate({ 20 | ...options, 21 | transform: ["translate(0%)", "translate(500%)"] 22 | })); 23 | ``` 24 | 25 | [Preview this example →](http://animateplus.com/examples/getting-started/) 26 | 27 | ## Options 28 | 29 | ### elements 30 | 31 | | Default | Type 32 | | :--- | :--- 33 | | `null` | String \| Element \| NodeList \| Array 34 | 35 | Determines the DOM elements to animate. You can either pass it a CSS selector or DOM elements. 36 | 37 | ```javascript 38 | animate({ 39 | elements: document.body.children, 40 | transform: ["rotate(0turn)", "rotate(1turn)"] 41 | }); 42 | ``` 43 | 44 | ### easing 45 | 46 | | Default | Type 47 | | :--- | :--- 48 | | `out-elastic` | String 49 | 50 | Determines the acceleration curve of your animation. 51 | 52 | | constant | accelerate | decelerate | accelerate-decelerate 53 | | :--- | :--- | :--- | :--- 54 | | linear | in-cubic | out-cubic | in-out-cubic 55 | | | in-quartic | out-quartic | in-out-quartic 56 | | | in-quintic | out-quintic | in-out-quintic 57 | | | in-exponential | out-exponential | in-out-exponential 58 | | | in-circular | out-circular | in-out-circular 59 | | | in-elastic | out-elastic | in-out-elastic 60 | 61 | The amplitude and period of elastic easings can be configured by providing space-separated values. 62 | Amplitude defaults to `1`, period to `0.4`. 63 | 64 | ```javascript 65 | // Increase elasticity 66 | animate({ 67 | elements: "span", 68 | easing: "out-elastic 1.4 0.2", 69 | transform: ["translate(0px)", "translate(500px)"] 70 | }); 71 | ``` 72 | 73 | ### duration 74 | 75 | | Default | Type 76 | | :--- | :--- 77 | | `1000` | Number \| Function 78 | 79 | Determines the duration of your animation in milliseconds. By passing it a callback, you can define 80 | a different duration for each element. The callback takes the index of each element as its argument 81 | and returns a number. 82 | 83 | ```javascript 84 | // First element fades out in 1s, second element in 2s, etc. 85 | animate({ 86 | elements: "span", 87 | easing: "linear", 88 | duration: index => (index + 1) * 1000, 89 | opacity: [1, 0] 90 | }); 91 | ``` 92 | 93 | ### delay 94 | 95 | | Default | Type 96 | | :--- | :--- 97 | | `0` | Number \| Function 98 | 99 | Determines the delay of your animation in milliseconds. By passing it a callback, you can define 100 | a different delay for each element. The callback takes the index of each element as its argument 101 | and returns a number. 102 | 103 | ```javascript 104 | // First element fades out after 1s, second element after 2s, etc. 105 | animate({ 106 | elements: "span", 107 | easing: "linear", 108 | delay: index => (index + 1) * 1000, 109 | opacity: [1, 0] 110 | }); 111 | ``` 112 | 113 | ### loop 114 | 115 | | Default | Type 116 | | :--- | :--- 117 | | `false` | Boolean 118 | 119 | Determines if the animation should repeat. 120 | 121 | ### direction 122 | 123 | | Default | Type 124 | | :--- | :--- 125 | | `normal` | String 126 | 127 | Determines the direction of the animation. `reverse` runs the animation backwards, `alternate` 128 | switches direction after each iteration if the animation loops. 129 | 130 | ### speed 131 | 132 | | Default | Type 133 | | :--- | :--- 134 | | `1` | Number 135 | 136 | Determines the animation playback rate. Useful in the authoring process to speed up some parts of a 137 | long sequence (value above 1) or slow down a specific animation to observe it (value below 1). 138 | 139 | ### optimize 140 | 141 | | Default | Type 142 | | :--- | :--- 143 | | `false` | Boolean 144 | 145 | Forces hardware acceleration during an animation if set to `true`. Unless you experience performance 146 | issues, it's recommended to leave it off as hardware acceleration comes with potentially harmful 147 | side-effects. 148 | 149 | ### blur 150 | 151 | | Default | Type 152 | | :--- | :--- 153 | | `null` | Object \| Function 154 | 155 | Simulates a motion blur effect. Takes an object or a function returning an object that specifies the 156 | strength of the directional blur on the `x` and `y` axes. A missing axis defaults to `0`, which 157 | disables the blur on that axis. 158 | 159 | ```javascript 160 | animate({ 161 | elements: "circle", 162 | easing: "out-exponential", 163 | duration: 2500, 164 | loop: true, 165 | direction: "alternate", 166 | blur: {x: 20, y: 2}, 167 | transform: ["translate(0%)", "translate(80%)"] 168 | }); 169 | ``` 170 | 171 | [Preview this example →](http://animateplus.com/examples/motion-blur/) 172 | 173 | ### change 174 | 175 | | Default | Type 176 | | :--- | :--- 177 | | `null` | Function 178 | 179 | Defines a callback invoked on every frame of the animation. The callback takes as its argument the 180 | animation progress (between 0 and 1) and can be used on its own without being tied to `elements`. 181 | 182 | ```javascript 183 | // Linearly outputs the percentage increase during 5s 184 | animate({ 185 | duration: 5000, 186 | easing: "linear", 187 | change: progress => 188 | document.body.textContent = `${Math.round(progress * 100)}%` 189 | }); 190 | ``` 191 | 192 | ## Animations 193 | 194 | Animate Plus lets you animate HTML and SVG elements with any property that takes numeric values, 195 | including hexadecimal colors. 196 | 197 | ```javascript 198 | // Animate the radius and fill color of an SVG circle 199 | animate({ 200 | elements: "circle", 201 | r: [0, 50], 202 | fill: ["#80f", "#fc0"] 203 | }); 204 | ``` 205 | 206 | Each property you animate needs an array defining the start and end values. For convenience, you can 207 | omit everything but the numbers in the end values. 208 | 209 | ```javascript 210 | // Same as ["translate(0px)", "translate(100px)"] 211 | animate({ 212 | elements: "span", 213 | transform: ["translate(0px)", 100] 214 | }); 215 | ``` 216 | 217 | These arrays can optionally be returned by a callback that takes the index of each element, just 218 | like with [duration](#duration) and [delay](#delay). 219 | 220 | ```javascript 221 | // First element translates by 100px, second element by 200px, etc. 222 | animate({ 223 | elements: "span", 224 | transform: index => ["translate(0px)", (index + 1) * 100] 225 | }); 226 | ``` 227 | 228 | ## Promise 229 | 230 | `animate()` returns a promise which resolves once the animation finishes. The promise resolves to 231 | the object initially passed to `animate()`, making animation chaining straightforward and 232 | convenient. The [Getting started](#getting-started) section gives you a basic promise example. 233 | 234 | Since Animate Plus relies on native promises, you can benefit from all the usual features promises 235 | provide, such as `Promise.all`, `Promise.race`, and especially `async/await` which makes animation 236 | timelines easy to set up. 237 | 238 | ```javascript 239 | const play = async () => { 240 | const options = await animate({ 241 | elements: "span", 242 | duration: 3000, 243 | transform: ["translateY(-100vh)", 0] 244 | }); 245 | 246 | await animate({ 247 | ...options, 248 | transform: ["rotate(0turn)", 1] 249 | }); 250 | 251 | await animate({ 252 | ...options, 253 | duration: 800, 254 | easing: "in-quintic", 255 | transform: ["scale(1)", 0] 256 | }); 257 | }; 258 | 259 | play(); 260 | ``` 261 | 262 | [Preview this example →](http://animateplus.com/examples/timeline/) 263 | 264 | ## Additional functions 265 | 266 | ### stop 267 | 268 | Stops the animations on the [elements](#elements) passed as the argument. 269 | 270 | ```javascript 271 | import {stop} from "/animateplus.js"; 272 | 273 | animate({ 274 | elements: "span", 275 | easing: "linear", 276 | duration: index => 8000 + index * 200, 277 | loop: true, 278 | transform: ["rotate(0deg)", 360] 279 | }); 280 | 281 | document.addEventListener("click", ({target}) => stop(target)); 282 | ``` 283 | 284 | [Preview this example →](http://animateplus.com/examples/stop/) 285 | 286 | ### delay 287 | 288 | Sets a timer in milliseconds. It differentiates from `setTimeout()` by returning a promise and being 289 | more accurate, consistent and battery-friendly. The [delay](#delay) option relies internally on 290 | this method. 291 | 292 | ```javascript 293 | import {delay} from "/animateplus.js"; 294 | 295 | delay(500).then(time => console.log(`${time}ms elapsed`)); 296 | ``` 297 | 298 | ## Browser support 299 | 300 | Animate Plus is provided as a native ES2015 module, which means you may need to transpile it 301 | depending on your browser support policy. The library works as is using `