@microsoft/fast-animation

FAST Animation

Fast Animation is a library for simplifying the creation of animations and interactions using the Web Animation API.

   

Benefits

• Provides an abstraction layer over the Web Animation API while still allowing full access to its functionality.
• Simplifies complex animations on elements.
• Provides mechanisms for sequencing and grouping animation effects between elements.

Usage

Installation

npm install @microsoft/fast-animation

Getting started

The primary tools for creating animations are the AnimateTo and AnimateFrom classes. These classes allow you to apply animations to HTML elements:

var myHtmlElement = document.getElementById("myElement");
var myAnimation = new AnimateTo(myHtmlElement, { x: "30%", scale: 2 }, { duration: 300, delay: 20 });

// Play the animation.
myAnimation.play();

Sequencing and grouping classes are provided to help orchestrate more elaborate animations:

var mySequence = new AnimateSequence([
    new AnimateTo(element1, { x: 20 }),
    new AnimateTo(element2, { x: 20 }),
    new AnimateTo(element3, { x: 20 })
]);

// Attach an onFinish callback.
mySequence.onFinish = () => {
    window.prompt("Did you like our animations?");
}

// Play all animations, one after another. When completed, ask the user if they liked the animation sequence.
mySequence.play();

Package exports

AnimateTo | AnimateFrom

TheAnimateTo and AnimateFrom classes can be used to create a variety of complex animations. These classes allow you to specify which properties should be animating as well as information like easing curves, duration, delay, and more.

Constructor

constructor(el: HTMLElement, options?: Options, timing?: EffectTiming)

Both AnimateTo and AnimateFrom accept one required parameter and two optional parameters:

var myAnimation = new AnimateTo(myHtmlElement, { x: 20 }, { duration: 250 });

Options

The following options are used to construct the animation and configure which properties the animation should change:

• x: { number | string } adjusts the element's horizontal position. This property adjusts the transform property.
• y: { number | string } adjusts the element's vertical position. This property adjusts the transform property.
• scale: { number[] | number } adjusts the scale of the element. If given a number, scale applies to both x and y-axes. If given an array of two numbers, x and y scale independently. This property adjusts the transform property.
• rotate: { number } adjusts the rotation of the object by a number of degrees. This property adjusts the transform property.
• top: { string | number } adjusts the top property.
• right: { string | number } adjusts the right property.
• bottom: { string | number } adjusts the bottom property.
• left: { string | number } adjusts the left property.
• transformOrigin: { string } adjusts the origin of any transform effects applied via the animation.
• transformStyle: { string } applies the value to the transfrom-style property of the element.

Effect timing

The EffectTiming object is passed directly to the WAAPI and should conform to the AnimationEffectTiming.

Public methods

The public methods exposed by the AnimateTo and AnimateFrom classes are play, pause, finish, cancel, and reverse. For more information on what these methods do, see the corresponding method exposed by the WAAPI Animation object.

Life cycle hooks

• If onFinish: () => void is provided, onFinish is called when the animation has completed.
• If onCancel: () => void is provided, onCancel is called when (and if) the animation is canceled.

AnimateGroup | AnimateSequence

The AnimateGroup and AnimateSequence classes are both classes that allow you to group and play animations together. Each takes an array of AnimateTo or AnimateFrom objects and provides an API to play, pause, finish, cancel, and reverse the collection of animations. AnimateGroup allows you to control all animations simultaneously while AnimateSequence allows you to control all animations in a sequence:

var myAnimationGroup = new AnimateGroup([
    new AnimateTo(element1),
    new AnimateTo(element2)
]);

var myAnimationSequence = new AnimateSequence([
    new AnimateTo(element3),
    new AnimateTo(element4)
]);

// AnimateGroup plays all animations at the same time.
myAnimationGroup.play();

// AnimateSequence plays all animations one after another in array order.
myAnimationSequence.play();

Constructor

Both AnimateGroup and AnimateSequence accept an array of AnimateTo and AnimateFrom objects:

constructor(AnimateTo[] | AnimateFrom[])

Public methods

The public methods exposed by the AnimateGroup and AnimateSequence classes are play, pause, finish, cancel, and reverse.

Life cycle hooks

If onFinish: () => void is provided, onFinish is called when the animation has completed.

Testing

• Run yarn dev-server:react to view the React examples (localhost:9005).
• Run yarn test to run unit-tests.

Dependencies

This system uses the emerging Web Animations API that is not supported in all browsers. To provide the broadest support, we recommend you include the web animations polyfill (use the 'next' version).

The polyfill assumes several global variables exist, and in our experience, it has caused polymorphic JavaScript to fail to compile with tools like TypeScript and Babel. There are also other advantages to CDN files, so we've chosen to take the Web Animations API polyfill as a peer dependency.

Find the polyfill and documentation here.

Additional resources

MDN Web Animations API documentation

Can I Use: Web Animations API