3 `neon-animation` is a suite of elements and behaviors to implement pluggable animated transitions for Polymer Elements using [Web Animations](https://w3c.github.io/web-animations/).
5 *Warning: The API may change.*
7 * [A basic animatable element](#basic)
8 * [Animation configuration](#configuration)
9 * [Animation types](#configuration-types)
10 * [Configuration properties](#configuration-properties)
11 * [Using multiple animations](#configuration-multiple)
12 * [Running animations encapsulated in children nodes](#configuration-encapsulation)
13 * [Page transitions](#page-transitions)
14 * [Shared element animations](#shared-element)
15 * [Declarative page transitions](#declarative-page)
16 * [Included animations](#animations)
20 ## A basic animatable element
22 Elements that can be animated should implement the `Polymer.NeonAnimatableBehavior` behavior, or `Polymer.NeonAnimationRunnerBehavior` if they're also responsible for running an animation.
28 Polymer.NeonAnimationRunnerBehavior
34 // provided by neon-animation/animations/scale-down-animation.html
35 name: 'scale-down-animation',
42 // this event is fired when the animation finishes
43 'neon-animation-finish': '_onNeonAnimationFinish'
46 // run scale-down-animation
49 _onNeonAnimationFinish: function() {
50 console.log('animation done!');
55 [Live demo](http://morethanreal.github.io/neon-animation-demo/bower_components/neon-animation/demo/doc/basic.html)
57 <a name="configuration"></a>
58 ## Animation configuration
60 <a name="configuration-types"></a>
63 An element might run different animations, for example it might do something different when it enters the view and when it exits from view. You can set the `animationConfig` property to a map from an animation type to configuration.
69 Polymer.NeonAnimationRunnerBehavior
79 // provided by neon-animation/animations/scale-up-animation.html
80 name: 'scale-up-animation',
84 // provided by neon-animation-animations/fade-out-animation.html
85 name: 'fade-out-animation',
93 'neon-animation-finish': '_onNeonAnimationFinish'
97 this.style.display = 'inline-block';
98 // run scale-up-animation
99 this.playAnimation('entry');
103 // run fade-out-animation
104 this.playAnimation('exit');
106 _onNeonAnimationFinish: function() {
108 this.style.display = 'none';
114 [Live demo](http://morethanreal.github.io/neon-animation-demo/bower_components/neon-animation/demo/doc/types.html)
116 You can also use the convenience properties `entryAnimation` and `exitAnimation` to set `entry` and `exit` animations:
121 value: 'scale-up-animation'
124 value: 'fade-out-animation'
129 <a name="configuration-properties"></a>
130 ### Configuration properties
132 You can pass additional parameters to configure an animation in the animation configuration object.
133 All animations should accept the following properties:
135 * `name`: The name of an animation, ie. an element implementing `Polymer.NeonAnimationBehavior`.
136 * `node`: The target node to apply the animation to. Defaults to `this`.
137 * `timing`: Timing properties to use in this animation. They match the [Web Animations Animation Effect Timing interface](https://w3c.github.io/web-animations/#the-animationeffecttiming-interface). The
138 properties include the following:
139 * `duration`: The duration of the animation in milliseconds.
140 * `delay`: The delay before the start of the animation in milliseconds.
141 * `easing`: A timing function for the animation. Matches the CSS timing function values.
143 Animations may define additional configuration properties and they are listed in their documentation.
145 <a name="configuration-multiple"></a>
146 ### Using multiple animations
148 Set the animation configuration to an array to combine animations, like this:
154 // fade-in-animation is run with a 50ms delay from slide-down-animation
156 name: 'slide-down-animation',
159 name: 'fade-in-animation',
168 <a name="configuration-encapsulation"></a>
169 ### Running animations encapsulated in children nodes
171 You can include animations in the configuration that are encapsulated in a child element that implement `Polymer.NeonAnimatableBehavior` with the `animatable` property.
177 // run fade-in-animation on this, and the entry animation on this.$.myAnimatable
179 {name: 'fade-in-animation', node: this},
180 {animatable: this.$.myAnimatable, type: 'entry'}
187 <a name="page-transitions"></a>
190 *The artist formerly known as `<core-animated-pages>`*
192 The `neon-animated-pages` element manages a set of pages to switch between, and runs animations between the page transitions. It implements the `Polymer.IronSelectableBehavior` behavior. Each child node should implement `Polymer.NeonAnimatableBehavior` and define the `entry` and `exit` animations. During a page transition, the `entry` animation is run on the new page and the `exit` animation is run on the old page.
194 <a name="shared-element"></a>
195 ### Shared element animations
197 Shared element animations work on multiple nodes. For example, a "hero" animation is used during a page transition to make two elements from separate pages appear to animate as a single element. Shared element animation configurations have an `id` property that identify they belong in the same animation. Elements containing shared elements also have a `sharedElements` property defines a map from `id` to element, the element involved with the animation.
199 In the incoming page:
206 // the incoming page defines the 'entry' animation
208 name: 'hero-animation',
225 In the outgoing page:
232 // the outgoing page defines the 'exit' animation
234 name: 'hero-animation',
244 'hero': this.$.otherHero
251 <a name="declarative-page"></a>
252 ### Declarative page transitions
254 For convenience, if you define the `entry-animation` and `exit-animation` attributes on `<neon-animated-pages>`, those animations will apply for all page transitions.
259 <neon-animated-pages id="pages" class="flex" selected="[[selected]]" entry-animation="slide-from-right-animation" exit-animation="slide-left-animation">
260 <neon-animatable>1</neon-animatable>
261 <neon-animatable>2</neon-animatable>
262 <neon-animatable>3</neon-animatable>
263 <neon-animatable>4</neon-animatable>
264 <neon-animatable>5</neon-animatable>
265 </neon-animated-pages>
268 The new page will slide in from the right, and the old page slide away to the left.
270 <a name="animations"></a>
271 ## Included animations
273 Single element animations:
275 * `fade-in-animation` Animates opacity from `0` to `1`.
276 * `fade-out-animation` Animates opacity from `1` to `0`.
277 * `scale-down-animation` Animates transform from `scale(1)` to `scale(0)`.
278 * `scale-up-animation` Animates transform from `scale(0)` to `scale(1)`.
279 * `slide-down-animation` Animates transform from `translateY(-100%)` to `none`.
280 * `slide-up-animation` Animates transform from `none` to `translateY(-100%)`.
281 * `slide-left-animation` Animates transform from `none` to `translateX(-100%)`;
282 * `slide-right-animation` Animates transform from `none` to `translateX(100%)`;
283 * `slide-from-left-animation` Animates transform from `translateX(-100%)` to `none`;
284 * `slide-from-right-animation` Animates transform from `translateX(100%)` to `none`;
285 * `transform-animation` Animates a custom transform.
287 Note that there is a restriction that only one transform animation can be applied on the same element at a time. Use the custom `transform-animation` to combine transform properties.
289 Shared element animations
291 * `hero-animation` Animates an element such that it looks like it scales and transforms from another element.
292 * `ripple-animation` Animates an element to full screen such that it looks like it ripples from another element.
295 * `cascaded-animation` Applys an animation to an array of elements with a delay between each.
300 * [Grid to full screen](http://morethanreal.github.io/neon-animation-demo/bower_components/neon-animation/demo/grid/index.html)
301 * [Animation on load](http://morethanreal.github.io/neon-animation-demo/bower_components/neon-animation/demo/load/index.html)
302 * [List item to detail](http://morethanreal.github.io/neon-animation-demo/bower_components/neon-animation/demo/list/index.html) (For narrow width)
303 * [Dots to squares](http://morethanreal.github.io/neon-animation-demo/bower_components/neon-animation/demo/tiles/index.html)
304 * [Declarative](http://morethanreal.github.io/neon-animation-demo/bower_components/neon-animation/demo/declarative/index.html)