KUTE.js

Getting Started

Welcome to KUTE.js API documentation, here we're going to talk about how to download, install, use, control and set up cross browser animations, in great detailed. KUTE.js can be found on CDN and also npm and Bower repositories with all it's features and tools.

Bower and NPM

You can install KUTE.js package by using either Bower or NPM.

$ npm install --save kute.js
# Or
$ bower install --save kute.js

Websites

In your website add the following code, the best would be to put it at the end of your body tag:

<script src="https://cdn.jsdelivr.net/kute.js/0.9.5/kute.min.js"></script> <!-- core KUTE.js -->

Also you can include the tools that you need for your project:

<script src="https://cdn.jsdelivr.net/kute.js/0.9.5/kute-jquery.min.js"></script> <!-- jQuery Plugin -->
<script src="https://cdn.jsdelivr.net/kute.js/0.9.5/kute-easing.min.js"></script> <!-- Bezier Easing Functions -->
<script src="https://cdn.jsdelivr.net/kute.js/0.9.5/kute-physics.min.js"></script> <!-- Physics Easing Functions -->

Your awesome animation coding would follow after these script links.

Ideal HTML Template

You need to know when users' browser is a legacy one in order to use KUTE.js only for what browsers can actually do. A quick note here: IE8 doesn't support any transform property or RGBA colors while IE9 can only do 2D transformations. Check the 2D transforms and the 3D transforms browser support list for more information.

Don't use Modernizr, the best thing we can actually do is use the Microsoft's synthax for it's own legacy browsers, so here's how a very basic HTML template for your websites would look like:

<!DOCTYPE html>
	<!--[if lt IE 8]><html class="ie prehistory" lang="en"><![endif]-->			
	<!--[if IE 8]><html class="ie ie8" lang="en"><![endif]-->			
	<!--[if IE 9]><html class="ie ie9" lang="en"><![endif]-->			
	<!--[if !IE]><!--> <html lang="en"> <!--<![endif]-->				
	<head>
		<meta charset="utf-8">
		<meta http-equiv="X-UA-Compatible" content="IE=edge">
		<meta name="viewport" content="width=device-width, initial-scale=1">				
		<!-- SEO meta here  -->					
		<!-- add your CSS here  -->				
		<!-- add polyfills  -->
		<script src="https://cdn.polyfill.io/v2/polyfill.js?features=default,getComputedStyle|gated"> </script>
	</head>					
	<body>
		<!-- site content here -->	
		<!-- scripts go here -->				
	</body>
</html>

For other legacy browsers there is a ton of ways to target them, quite efficiently I would say: there you go.

Main Methods

These methods allow you to create tween objects; here a tween object is essentially like an animation setup for a given HTML element, defining CSS properties, animation duration or repeat. The methods have different uses and performance scores while making it easy to work with.

.to() method is the most simple method which allows you to create tween objects for animating CSS properties from a specific default value OR from current/computed value TO a desired value. It's performance is not the same as for the next two because it has to compute the default/current value on tween .start() and thus delays the animation for a cuple of miliseconds, but this feature is great for simple animations AND it has the ability to stack transform properties as they go, making smooth transform animations on chained tweens. See the .start() method for the solution for sync/delay issue.

Considering a given div element is already transparent, a super quick example would be:

KUTE.to(div,{opacity:1}).start()

.fromTo() method is the best way to build animations for BEST performance and absolute control. The tests prove this method to be the fastest methods but unlike the .to() method, it does not stack transform properties on chained tweens. Also, another advantage is the fact that you can set measurement units for both starting and end values, to avoid glitches. We've talked about this in the features page. So here's a quick example:

KUTE.fromTo(div,{opacity:1},{opacity:0}).start()

.Animate() method is only a fallback for the older KUTE.js versions and works as the .fromTo() method. It will be deprecated with later versions.

Tween Control Methods

These methods allows you to control when the animation starts or stops. Let's write a basic tween object to work with the methods:

var tween = KUTE.fromTo(div,{opacity:1},{opacity:0});

This tween object is now ready to work with the methods.

Starting Animations

.start() method starts animation for a given tween object. It can start the animation for both cached and non-cached objects. Unlike previous versions of KUTE.js, where animation started immediately after tween object creation, now you have to manually start them.

//cached object defined above
tween.start();

//non-cached object are created on the fly and garbage collected after animation has finised
KUTE.fromTo(div,{opacity:1},{opacity:0}).start();

//also start the tween at a certain time
tween.start(now); // where now must be the current or future time as number, see below

As you can see, you can also set a time for the animation to start, example: tween.start(myTimeValue). Having access to the method is useful when starting animation for large amounts of elements with same properties at the same time because using it properly eliminates any syncronization issue that may occur, even if you are using the .to() method. This applies to our performance test page as well, and the trick is super duper simple:

// step 1 - create an empty array and grab the elements to animate
var tweens = [], myElements = document.querySelector('.myManyElements');

// step 2 - define tween objects for each element
for (var i = 0; i < numberOfElements; i++) {
	var tween = KUTE.fromTo(myElements[i], fromValues, toValues, options);
	//now we populate the tweens array
	tweens.push(tween);
}

// step 3 - calculate the right time to start
// first we need the exact current time
var now = window.performance.now(); // this returns the exact current time in numeric format

// also we estimate/calculate an adjustment lag 
// depending on the number of the elements AND hardware capability
// maybe (numberOfElements / 16) would be an accurate value for PCs
var lag = 100; // number of miliseconds for the script to built tween objects for all elements

// step4 - we just start the animation for all elements at once
for (var i = 0; i < numberOfElements; i++) {
	tweens[i].start(now+lag);
}

If you care to see the actual working code, check it in the perf.js file.

Stopping Animation

.stop() method stops animation for a given tween object while animating. You cannot stop the animation for tween objects created on the fly, only for cached objects. Let's assume that for the given tween we decide to stop the animation via click action:

stopButton.addEventListener('click', function(){
	tween.stop();
}, false);

Pausing Animation

.pause() method freezez the animation at any given time for a given tween object, and unlike the .stop() method, this one allows resuming the animation on a later use of the next method .play().

pauseButton.addEventListener('click', function(){
	tween.pause();
}, false);

Resuming Paused Animation

.play() or .resume() methods allows you to resume an animation for a given tween object only if it was paused or else will produce no effect.

playButton.addEventListener('click', function(){
	tween.play(); // or tween.resume();
}, false);

Chaining Tweens

.chain() method can be used to chain tweens together. When the animation finishes for a given tween, it triggers the animation start for another tween.

var tween2 = KUTE.fromTo(div,{left:50},{left:0});

//the first tween chains the new tween
tween.chain(tween2);

//the new tween chains the first one creating a loop
tween2.chain(tween);

It's also possible to chain multiple tweens, just as shown in the below example, but the one that finishes last (has longest delay and duration together) should be used last in the .chain() method arguments list. Why? Because when a tween is finished it triggers cancelAnimationFrame() and KUTE.js will stop "ticking" causing all other chained tweens to stop prematurelly.

//chain multiple tweens
tween.chain(tween1,tween2);

Tween Options

Common Options

These options affect all types of tweens, no matter the properties used or context.

duration: 500 option allows you to set the animation duration in miliseconds. The default value is 700.

repeat: 20 option allows you to run the animation of given tween multiple times. The default value is 0.

delay: 500 option allows you to schedule the tween animation after a certain number of miliseconds. The default value is 0.

repeatDelay: 500 option allows you to set a number of miliseconds delay between repeatable animations. If repeat option is set to 0, will produce no effect. The default value is 0.

yoyo: true/false option makes use of the internal reverse functionality to also animate from end to start for a given tween. This option requires that you use the repeat option with at least value 1. The default value is false.

easing: 'easingCubicInOut' option allows you to use a custom easing function for your animation. For more info on the easing functions, you need to see the example pages. The default value is linear.

Transform Options

These options only affect animation involving any property from CSS3 transform specs and have no effect on other CSS properties. While you can set perspective or perspective origin via CSS, these options are here to help, especially with full browser support and preffix free handling.

perspective: 500 option allows you to set a 3D transformation perspective for a given HTML element that is subject to transform animation. No default value.

perspectiveOrigin: "50% 50%" option allows you to set a perspectiveOrigin for a given HTML. This option has no default value and only accepts valid CSS values according to it's specs.

parentPerspective: 500 option allows you to set a 3D perspective for the parent of the HTML element subject to the transform animation.

parentPerspectiveOrigin: "50% 50%" option allows you to set a perspectiveOrigin for the parent of the HTML element subject to the transform animation. Also like the above similar options, this options only accepts valid CSS values.

Callback Options

These options also affect all types of tweens, and are bound by the tween control options and the internal update functions.

start: function option allows you to set a function to run once tween animation starts.

update: function option allows you to set a function to run on every frame.

pause: function option allows you to set a function to run when animation is paused.

resume: function option allows you to set a function to run when animation is resumed.

stop: function option allows you to set a function to run when animation is stopped.

complete: function option allows you to set a function to run when animation is finished.

A quick example would look like this:

//define a function
var callback = function(){
	//do some foo
}

//create object and start animating already
KUTE.fromTo(div,{left:150},{left:0},{complete: callback}).start();

Other

keepHex: true option allows you to always use HEX color format, even if you have used RGB or RGBA. This option is useful when tweening color properties on legacy browsers, however modern browsers may ignore this option for performance reasons.

Easing Functions

The easing functions generally make animations closer to reality and completely eliminate the boring factor for a given context. The most simple example to understand what they do, think of gravity. Dropping an object from a given height, will start moving to the ground with accelerated speed. If the object has some sort of bounciness like a ball, it will jump back up and up again, till the gravity will eventually stick the object to the ground.

What scientists observed and put in theory houndreads of years ago, later the pioneers of scripting started to implement the laws of physics into digital animation and came up with this notion of easing to describe the progression of movement. If you care to dig into the concept, here's an excellent resource some developers recommend. I would also recommend this one too.

Core Functions

Modern browsers that support transition can also make use of some generic easing functions via the CSS3 transition-timing-function:ease-out property, but in Javascript animation, we need some special functions. The popular Robert Penner's easing functions set is one of them, and is the default set included with KUTE.js because it's the fastest set I know in terms of performance. Some functions may lack a bit of accuracy but they cover the most animation needs. Generally the easing functions' names are built with keywords that describe the type of easing, like circular or exponential, and also the type of progression in and/or out.

To use them, simply set a tween option like so easing: KUTE.Easing.easingSinusoidalInOut or simply easing: 'easingSinusoidalInOut'.

linear is the default easing function and just as it sounds, it means that the animation has no acceleration or deceleration over time. While this one is basically boring, it's the fastest in all, and it's very useful when animating opacity or colors because we cannot really distinguish changes in speed for such cases, but mostly for movement.

curve based functions are the next set of easings we are going to tak about. They are basically the same, the only difference is the number of multipliers applied (better think of it like the more weight an object has, the more acceleration):

The In / Out explained:

back easing functions describe more complex animations (I would call them reverse gravity easings). They also come with in and/or out types of progression.

elasticity easing functions describe the kind of animation where the object is elastic. With in and/or out as well.

gravity based easing functions describe the kind of animation where the object has a certain degree of bounciness, like a ball. With in and/or out as well.

Cubic Bezier Functions

While modern browsers support CSS3 transition with transition-timing-function: cubic-bezier(0.1,0.5,0.8,0.5), in Javascript animation we need some specific functions to cover that kind of functionality. As mentioned in the features page, we are using a modified version of the cubic-bezier by Gaëtan Renaudeau. I believe this must be most accurate easing functions set.

You can use them either with easing: KUTE.Ease.bezier(mX1, mY1, mX2, mY2) or easing: 'bezier(mX1, mY1, mX2, mY2)', where mX1, mY1, mX2, mY2 are Float values from 0 to 1. You can find the right values you need right here.

There is also a pack of presets, and the keywords look very similar if you have used jQuery.Easing plugin before:

Physics Based Functions

KUTE.js also packs the dynamics physics easing functions by Michael Villar and I have to say these functions are amazing in terms of flexibility, control and performance. They allow you to control the friction, bounciness, frequency, elasticity, or multiple bezier points for your animations.

You can use them either with regular Javascript invocation as shown below and configure / visualize them on the author's website, while you can also use the pack of presets featuring mostly bezier based functions. Ok now, let's get to it:

The presets can be used both as a string easing:'physicsIn' or easing:KUTE.Physics.physicsIn(friction:200). The list is: