1 2Quick Start 3----------- 4 5To provide native Chrome Web Animation features (`Element.animate` and Playback 6Control) in other browsers, use `web-animations.min.js`. To explore all of the 7proposed Web Animations API, use `web-animations-next.min.js`. 8 9What is Web Animations? 10----------------------- 11 12Web Animations is a new JavaScript API for driving animated content on the web. 13By unifying the animation features of SVG and CSS, Web Animations unlocks 14features previously only usable declaratively, and exposes powerful, 15high-performance animation capabilities to developers. 16 17For more details see the 18[W3C specification](http://w3c.github.io/web-animations/). 19 20What is the polyfill? 21--------------------- 22 23The polyfill is a JavaScript implementation of the Web Animations API. It works 24on modern versions of all major browsers. For more details about browser 25support see <https://www.polymer-project.org/resources/compatibility.html>. 26 27Getting Started 28--------------- 29 30Here's a simple example of an animation that scales and changes the opacity of 31a `<div>` over 0.5 seconds. The animation alternates producing a pulsing 32effect. 33 34 <script src="web-animations.min.js"></script> 35 <div class="pulse" style="width:150px;">Hello world!</div> 36 <script> 37 var elem = document.querySelector('.pulse'); 38 var player = elem.animate([ 39 {opacity: 0.5, transform: "scale(0.5)"}, 40 {opacity: 1.0, transform: "scale(1)"} 41 ], { 42 direction: 'alternate', 43 duration: 500, 44 iterations: Infinity 45 }); 46 </script> 47 48Web Animations supports off-main-thread animations, and also allows procedural 49generation of animations and fine-grained control of animation playback. See 50<http://web-animations.github.io> for ideas and inspiration! 51 52Native Fallback 53--------------- 54 55When the polyfill runs on a browser that implements Element.animate and 56AnimationPlayer Playback Control it will detect and use the underlying native 57features. 58 59Different Build Targets 60----------------------- 61 62### web-animations.min.js 63 64Tracks the Web Animations features that are supported natively in browsers. 65Today that means Element.animate and Playback Control in Chrome. If you’re not 66sure what features you will need, start with this. 67 68### web-animations-next.min.js 69 70Contains all of web-animations.min.js plus features that are still undergoing 71discussion or have yet to be implemented natively. 72 73### web-animations-next-lite.min.js 74 75A cut down version of web-animations-next, it removes several lesser used 76property handlers and some of the larger and less used features such as matrix 77interpolation/decomposition. 78 79### Build Target Comparison 80 81| | web-animations | web-animations-next | web-animations-next-lite | 82|------------------------|:--------------:|:-------------------:|:------------------------:| 83|Size (gzipped) | 12.5kb | 14kb | 10.5kb | 84|Element.animate | ✔ | ✔ | ✔ | 85|Timing input (easings, duration, fillMode, etc.) for animations| ✔ | ✔ | ✔ | 86|Playback control | ✔ | ✔ | ✔ | 87|Support for animating lengths, transforms and opacity| ✔ | ✔ | ✔ | 88|Support for Animating other CSS properties| ✔ | ✔ | �� | 89|Matrix fallback for transform animations | ✔ | ✔ | �� | 90|Animation constructor | �� | ✔ | ✔ | 91|Simple Groups | �� | ✔ | ✔ | 92|Custom Effects | �� | ✔ | ✔ | 93|Timing input (easings, duration, fillMode, etc.) for groups</div>| �� | ��\* | �� | 94|Additive animation | �� | ��\* | �� | 95|Motion path | ��\* | ��\* | �� | 96|Modifiable animation timing| �� | ��\* | ��\* | 97|Modifiable group timing | �� | ��\* | ��\* | 98|Usable inline style\*\* | ✔ | ✔ | �� | 99 100\* support is planned for these features. 101\*\* see inline style caveat below. 102 103Caveats 104------- 105 106Some things won’t ever be faithful to the native implementation due to browser 107and CSS API limitations. These include: 108 109### Inline Style 110 111Inline style modification is the mechanism used by the polyfill to animate 112properties. Both web-animations and web-animations-next incorporate a module 113that emulates a vanilla inline style object, so that style modification from 114JavaScript can still work in the presence of animations. However, to keep the 115size of web-animations-next-lite as small as possible, the style emulation 116module is not included. When using this version of the polyfill, JavaScript 117inline style modification will be overwritten by animations. 118Due to browser constraints inline style modification is not supported on iOS 7 119or Safari 6 (or earlier versions). 120 121### Prefix handling 122 123The polyfill will automatically detect the correctly prefixed name to use when 124writing animated properties back to the platform. Where possible, the polyfill 125will only accept unprefixed versions of experimental features. For example: 126 127 var animation = new Animation(elem, {"transform": "translate(100px, 100px)"}, 2000); 128 129will work in all browsers that implement a conforming version of transform, but 130 131 var animation = new Animation(elem, {"-webkit-transform": "translate(100px, 100px)"}, 2000); 132 133will not work anywhere. 134 135API and Specification Feedback 136------------------------------ 137 138File an issue on GitHub: <https://github.com/w3c/web-animations/issues/new>. 139Alternatively, send an email to <public-fx@w3.org> with subject line 140“[web-animations] … message topic …” 141([archives](http://lists.w3.org/Archives/Public/public-fx/)). 142 143Polyfill Issues 144--------------- 145 146Report any issues with this implementation on GitHub: 147<https://github.com/web-animations/web-animations-next/issues/new>. 148 149Breaking changes 150---------------- 151 152When we make a potentially breaking change to the polyfill's API 153surface (like a rename) where possible we will continue supporting the 154old version, deprecated, for three months, and ensure that there are 155console warnings to indicate that a change is pending. After three 156months, the old version of the API surface (e.g. the old version of a 157function name) will be removed. *If you see deprecation warnings you 158can't avoid it by not updating*. 159 160We also announce anything that isn't a bug fix on 161[web-animations-changes@googlegroups.com](https://groups.google.com/forum/#!forum/web-animations-changes). 162