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