neon-animation

neon-animation

neon-animation is a suite of elements and behaviors to implement pluggable animated transitions for Polymer Elements using Web Animations.

Warning: The API may change.

A basic animatable element

Elements that can be animated should implement the Polymer.NeonAnimatableBehavior behavior, or Polymer.NeonAnimationRunnerBehavior if they’re also responsible for running an animation.

Polymer({
  is: 'my-animatable',
  behaviors: [
    Polymer.NeonAnimationRunnerBehavior
  ],
  properties: {
    animationConfig: {
      value: function() {
        return {
          // provided by neon-animation/animations/scale-down-animation.html
          name: 'scale-down-animation',
          node: this
        }
      }
    }
  },
  listeners: {
    // this event is fired when the animation finishes
    'neon-animation-finish': '_onNeonAnimationFinish'
  },
  animate: function() {
    // run scale-down-animation
    this.playAnimation();
  },
  _onNeonAnimationFinish: function() {
    console.log('animation done!');
  }
});

Live demo

Animation configuration

Animation types

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.

Polymer({
  is: 'my-dialog',
  behaviors: [
    Polymer.NeonAnimationRunnerBehavior
  ],
  properties: {
    opened: {
      type: Boolean
    },
    animationConfig: {
      value: function() {
        return {
          'entry': {
            // provided by neon-animation/animations/scale-up-animation.html
            name: 'scale-up-animation',
            node: this
          },
          'exit': {
            // provided by neon-animation-animations/fade-out-animation.html
            name: 'fade-out-animation',
            node: this
          }
        }
      }
    }
  },
  listeners: {
    'neon-animation-finish': '_onNeonAnimationFinish'
  },
  show: function() {
    this.opened = true;
    this.style.display = 'inline-block';
    // run scale-up-animation
    this.playAnimation('entry');
  },
  hide: function() {
    this.opened = false;
    // run fade-out-animation
    this.playAnimation('exit');
  },
  _onNeonAnimationFinish: function() {
    if (!this.opened) {
      this.style.display = 'none';
    }
  }
});

Live demo

You can also use the convenience properties entryAnimation and exitAnimation to set entry and exit animations:

properties: {
  entryAnimation: {
    value: 'scale-up-animation'
  },
  exitAnimation: {
    value: 'fade-out-animation'
  }
}

Configuration properties

You can pass additional parameters to configure an animation in the animation configuration object. All animations should accept the following properties:

Animations may define additional configuration properties and they are listed in their documentation.

Using multiple animations

Set the animation configuration to an array to combine animations, like this:

animationConfig: {
  value: function() {
    return {
      // fade-in-animation is run with a 50ms delay from slide-down-animation
      'entry': [{
        name: 'slide-down-animation',
        node: this
      }, {
        name: 'fade-in-animation',
        node: this,
        timing: {delay: 50}
      }]
    }
  }
}

Running animations encapsulated in children nodes

You can include animations in the configuration that are encapsulated in a child element that implement Polymer.NeonAnimatableBehavior with the animatable property.

animationConfig: {
  value: function() {
    return {
      // run fade-in-animation on this, and the entry animation on this.$.myAnimatable
      'entry': [
        {name: 'fade-in-animation', node: this},
        {animatable: this.$.myAnimatable, type: 'entry'}
      ]
    }
  }
}

Page transitions

The artist formerly known as <core-animated-pages>

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.

Shared element animations

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.

In the incoming page:

properties: {
  animationConfig: {
    value: function() {
      return {
        // the incoming page defines the 'entry' animation
        'entry': {
          name: 'hero-animation',
          id: 'hero',
          toPage: this
        }
      }
    }
  },
  sharedElements: {
    value: function() {
      return {
        'hero': this.$.hero
      }
    }
  }
}

In the outgoing page:

properties: {
  animationConfig: {
    value: function() {
      return {
        // the outgoing page defines the 'exit' animation
        'exit': {
          name: 'hero-animation',
          id: 'hero',
          fromPage: this
        }
      }
    }
  },
  sharedElements: {
    value: function() {
      return {
        'hero': this.$.otherHero
      }
    }
  }
}

Declarative page transitions

For convenience, if you define the entry-animation and exit-animation attributes on <neon-animated-pages>, those animations will apply for all page transitions.

For example:

<neon-animated-pages id="pages" class="flex" selected="[[selected]]" entry-animation="slide-from-right-animation" exit-animation="slide-left-animation">
  <neon-animatable>1</neon-animatable>
  <neon-animatable>2</neon-animatable>
  <neon-animatable>3</neon-animatable>
  <neon-animatable>4</neon-animatable>
  <neon-animatable>5</neon-animatable>
</neon-animated-pages>

The new page will slide in from the right, and the old page slide away to the left.

Included animations

Single element animations:

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.

Shared element animations

Group animations

Demos