clarity-animation

v1.0.25

Published

2 years ago

Unopinionated animation library.

Downloads

Getting Started with Clarity Animation

Install Clarity Animation with npm.

npm install clarity-animation

Browser support

IE Edge
Chrome 38+
Firefox 51+
Opera 42+
iOS Safari 9.3
Android Browser 4.4.4
Chrome For Android 55+

Examples

Use Cases

Because Clarity Animation uses UMD (Universal Module Declaration) it can work with a variety of technologies. It can be used with CommonJs, AMD, or SystemJs. Just decide which module system works for you and import clarity-animation. This also means that if you use transpilers like Babel or Typescript you can also use it. Even if you don't use a module system you can still use clarity-animation. It will detect that there isn't any module system and assign clarityAnimation to the global object. So go out and make applications prettier. Happy animating!

Clarity Animation Mission

The clarity-animation package wants to solve your complicated animation needs in simplest of patterns. Making a application beautiful shouldn't be hard. So if there is a better way to describe animations and timelines let us know, and lets have a great conversation.

Animations vs Timelines

In clarity-animation there are two basic things you need to use, the Animation classes and Timeline classes. The animation class gives you the ability to describe the properties to change, the easing, and the duration. We found early on in our development we needed to be able to compose animations with different easings and durations. Timelines answer that problem. They allow you to compose animations together in a way that gaurantees the animations to remain in sync with one another, forward or backward. Since Timelines are really animations, this also means you can compose timelines with in timelines. Really the complexity of the animations is limitless but the ease of composing them is simple.

Examples

With in the clarity-animation package is an example folder. Please browse through the examples. It will teach you many things that documentation wont. They also provide a foundation of ideas that can be used while building animations.

Whats included?

Animation
CssAnimation
CustomRenderAnimation
ElementPathAnimation
Timeline
PercentageTimeline

There are seven different classes to make animations with. There is the root class Animation, from which all classes are derived. CustomRenderAnimation which allows you to provider a custom renderer. CssAnimation animates an object with properties that resemble css names and understands the units involved with those property names. ElementPathAnimation animates elements through bezier curves with points and controls. Timeline allows you to compose many animations into a concert of animations using offsets. PercentageTimeline does the same as the Timeline but instead uses the principles of startAt and endAt to compose the animations.

Clarity Animation

npm install clarity-animation

Add a index.html file to the directory so it looks something like this.

* index.html
* node_modules
    * clarity-animation

Copy the contents of this example and paste it into the index.html file.

<html>
    <head>
        <title>Script Tag Exmaple</title>
        <style>
            .box {
                width: 100px;
                height:100px;
                border: 1px solid #000000;
            }
        </style>
    </head>
    <body>

        <div id="my-box" class="box"></div>

        <script src="./node_modules/clarity-animation/dist/main.js"></script>
        <script>
                var CssAnimation = clarityAnimation.CssAnimation;
                var box = document.querySelector("#my-box");

                var animation = new CssAnimation({
                    render: function(values){
                        Object.keys(values).forEach(function(property){
                            box.style[property] = values[property];
                        });
                    },
                    properties: {
                        backgroundColor: {
                            from: "rgba(0,0,0,0)",
                            to: "#ff0000"
                        }
                    },
                    duration: 10000,
                    easing: "easeOutExpo"
                });

                animation.playToEndAsync();
        </script>
    </body>
</html>

Clarity Animation with Reactjs

In the root of your Reactjs folder install Clarity Animation with npm.

npm install clarity-animation --save

Now that Clarity Animation is installed start using it in one of your components.

import React, { Component } from "react";
import { CssAnimation } from "clarity-animation";

const myStyles = {
    backgroundColor: "rgba(100,100,200,0.5)",
    width: "100px",
    height: "100px"
};

class MyComponent extends Component {
    constructor(props){
        super(props);

        var animation = new CssAnimation({
            target: myStyles,
            properties: {
                backgroundColor: {
                    from: myStyles.backgroundColor,
                    to: "#ff0000"
                }
            },
            duration: 10000,
            easing: "easeOutExpo"
        });

        animation.observe("tick", ()=>{
            this.forceUpdate();
        });

        this.animation = animation;
    }
    componentDidMount(){
        this.animation.playToEndAsync().then(()=>{
            console.log("Finished Animation");
        });
    }
    render(){

        return (
            <div style={myStyles}>
                Hello Animation!
            </div>            
        );

    }

}

Requirejs with Clarity Animation

npm install clarity-animation

After running the npm command, downloading requirejs , and adding a index.html file, the folder structure would look something like this.

- index.html
- require.js
- node_modules
    -clarity-animation

Copy the contents of this example and paste it into the index.html file.

<html>
    <head>
        <title>Using Animation</title>
    </head>
    <body>
        <script src="require.js"></script>
        <script>
            require(["./node_modules/clarity-animation/dist/main.js"], function(clarityAnimation){
                var CssAnimation = clarityAnimation.CssAnimation;

                var target = {
                    backgroundColor: "#123456"
                };

                var animation = new CssAnimation({
                    target: target,
                    properties: {
                        backgroundColor: {
                            from: target.backgroundColor,
                            to: "#ff0000"
                        }
                    },
                    duration: 1000,
                    easing: "easeOutExpo"
                });
                                    
                animation.observe("tick", function(){
                    document.body.style.backgroundColor = target.backgroundColor;
                });

                animation.playToEndAsync();
                });
        </script>
    </body>
</html>

Documentation

Animation Easings

linear (Default)
easeInQuad
easeOutQuad
easeInOutQuad
easeInCubic
easeOutCubic
easeInOutCubic
easeInQuart
easeOutQuart
easeInOutQuart
easeInQuint
easeOutQuint
easeInOutQuint
easeInSine
easeOutSine
easeInOutSine
easeInExpo
easeOutExpo
easeInOutExpo
easeInCirc
easeOutCirc
easeInOutCirc
easeInElastic
easeOutElastic
easeInOutElastic
easeInBack
easeOutBack
easeInOutBack
easeInBounce
easeOutBounce
easeInOutBounce

Repeating

There are two properties to control repeating. The first is the "repeat" property on the animation, and the "repeatDirection". The "repeat" property controls how many times the animation will repeat. You can use "Infinity" to mean.... well infinity and any integer to express the amount of times you would like the animation to repeat.

For "repeatDirection" you can use two values, 0 or 1. We have two static properties on the Animation class to help remember what is what. 0 is the default repeat which starts from the beginning, and 1 which is the alternating repeat. Alternating means that the animation will go back and forward like a swing.

...
animation.repeat = Infinity;
animation.repeatDirection = Animation.REPEAT_DEFAULT; 
...
// or
animation.repeat = 10;
animation.repeatDirection = Animation.REPEAT_ALTERNATE;

Animation

This class can animate any property on any object as long as its a number. If you would like to animate SVGs this is the class for you.

var obj = {
    width: 0,
    height: 0
};

var animation = new clarityAnimation.Animation({
    target: obj,
    properties: {
        width: {
            from: 0,
            to: 100
        },
        height: {
            from: 0,
            to: 100
        }
    },
    duration: 1000,
    easing: "easeOutExpo"
});

CustomRenderAnimation

This class allows you to decide how to render the current values. Check out the svg example.

var animation = new clarityAnimation.CustomRenderAnimation({
    render: (values)=>{
        Object.keys(values).forEach((propertyName)=>{
            svgCircle.setAttribute(propertyName, values[propertyName]);
        });
    },
    properties: {
        width: {
            from: 0,
            to: 100
        },
        height: {
            from: 0,
            to: 100
        }
    },
    duration: 1000,
    easing: "easeOutExpo"
});

Timeline

    var div = document.createElement("div");
    var div2 = document.createElement("div");

    var renderDiv = function(values){
        Object.keys(values).forEach(function(property){
            div.style[property] = values[property];
        });
    };

    var renderDiv2 = function(values){
        Object.keys(values).forEach(function(property){
            div2.style[property] = values[property];
        });
    };


    var opacityAnimation = new CssAnimation({
        render: renderDiv,
        properties: {
            opacity: {
                from: 0,
                to: 1
            }
        },
        duration: 2000,
        easing: "easing"
    });

    var moveAnimation = new CssAnimation({
        render: renderDiv2,
        properties: {
            left: {
                from: "0px",
                to: "100px"
            }
        },
        duration: 2000,
        easing: "easeOutExpo"
    });

    moveDiv2Animation = new CssAnimation({
        render: renderDiv2,
        properties: {
            left: {
                from: "100px",
                to: "200px"
            }
        },
        duration: 2000,
        easing: "easeOutExpo"
    });

    var timeline = new Timeline();
    timeline.add({
        animation: opacityAnimation,
        offset: 0
    },{
        animation: moveAnimation,
        offset: 0
    },{
        animation: moveDiv2Animation,
        offset: 0
    });

    timeline.play();

PercentageTimeline

PercentageTimeline really works well when thinking about a concert of animations. You just need to think about when something will start and finish. If you need an animation to start at the beginning and end half way through, and another animation to start half way through and end three quarters of the way through. This is the class for you. After deciding the composition, you can adjust the duration until its perfect.

    var div = document.createElement("div");
    var div2 = document.createElement("div");

    var renderDiv = function(values){
        Object.keys(values).forEach(function(property){
            div.style[property] = values[property];
        });
    };

    var renderDiv2 = function(values){
        Object.keys(values).forEach(function(property){
            div2.style[property] = values[property];
        });
    };


    var opacityAnimation = new CssAnimation({
        render: renderDiv,
        properties: {
            opacity: {
                from: 0,
                to: 1
            }
        },
        duration: 2000,
        easing: "easing"
    });

    var moveAnimation = new CssAnimation({
        render: renderDiv2,
        properties: {
            left: {
                from: "0px",
                to: "100px"
            }
        },
        duration: 2000,
        easing: "easeOutExpo"
    });

    moveDiv2Animation = new CssAnimation({
        render: renderDiv2,
        properties: {
            left: {
                from: "100px",
                to: "200px"
            }
        },
        duration: 2000,
        easing: "easeOutExpo"
    });

    var timeline = new PercentageTimeline(2000);
    timeline.add({
        animation: opacityAnimation,
        startAt: 0,
        endAt: 1
    },{
        animation: moveAnimation,
        startAt: 0,
        endAt: 0.5
    },{
        animation: moveDiv2Animation,
        startAt: 0.5,
        endAt: 1
    });

    timeline.play();

Methods on Animations and Timelines.

observe(type: string, callback )

Observable Events

start
end
tick
play
reverse
stop
pause
restart

...
animation.observe("tick", function(){
    console.log("tick");    
});
...

play( )

Plays the animation from its current position to the end.

...
animation.play();
...

playToEndAsync( ):Promise

Plays the animation from its current position to the end, and returns a Promise. When the animation makes it to the end of the animation, the promise is resolved. If any other actions are taken on the animation the promise will not be fulfilled.

...
animation.playToEndAsync();
...

playToPercentageAsync( percentage: number ):Promise

Plays the animation from its current position to the percentage given, and returns a Promise. When the animation makes it to the end of the animation, the promise is resolved. If any other actions are taken on the animation the promise will not be fulfilled. The percentage number is expected to be 0-100.

...
animation.playToPercentageAsync(50);
...

pause( )

Pauses the animation.

...
animation.pause();
...

restart( )

Restarts the animation from the beginning.

...
animation.restart();
...

reverse( )

Sends the animation in reverse from its current position to the beginning.

...
animation.reverse();
...

reverseToStartAsync( ):Promise

Sends the animation in reverse from its current position to the beginning. When the animation makes it to the beginning of the animation, the promise is resolved. If any other actions are taken on the animation the promise will not be fulfilled.

...
animation.reverseToStartAsync();
...

reverseToPercentageAsync( percentage: number ):Promise

Sends the animation in reverse from its current position to the percentage given. When the animation makes it to the beginning of the animation, the promise is resolved. If any other actions are taken on the animation the promise will not be fulfilled. The percentage number is expected to be 0-100.

...
animation.reverseToStartAsync(50);
...

seek( percentage: number )

If you seek when the animation is stopped, it will not render. Use pause then seek instead.

animation.pause().seek(0.3);

Or use

animation.seek(0.3).render();

Use stop and seek if you don't want the viewer to know that animation is positioned to some other time then what is rendered.

...
// Seek to this percentage of the animation.
animation.seek(0.5);
...

setTimeScale( percentage: number )

...
// Go twice as fast
animation.setTimeScale(2);
...

getTimeScale()

...
var scale = animation.getTimeScale();
...

getProgress()

...
var progress = animation.getProgress();
...

render()

This forces an update on the properties being animated.

...
animation.render();
...

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme

Getting Started with Clarity Animation

Browser support

Examples

Use Cases

Clarity Animation Mission

Animations vs Timelines

Examples

Whats included?

Clarity Animation

Clarity Animation with Reactjs

Requirejs with Clarity Animation

Documentation

Animation Easings

Repeating

Animation

CustomRenderAnimation

Timeline

PercentageTimeline

Methods on Animations and Timelines.

observe(type: string, callback )

play( )

playToEndAsync( ):Promise

playToPercentageAsync( percentage: number ):Promise

pause( )

restart( )

reverse( )

reverseToStartAsync( ):Promise

reverseToPercentageAsync( percentage: number ):Promise

seek( percentage: number )

setTimeScale( percentage: number )

getTimeScale()

getProgress()

render()