Public Methods

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

Single Tween Object

As the heading suggests, the following two methods allow you to create tween objects for individual HTML elements.

.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 .fromTo() method as it has to compute the default/current value on tween .start() and thus delays the animation for a couple of miliseconds; still 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()

As you might have guessed, this method is useful for creating simple animations such as for scroll, hide/reveal elements, or generally when you don't know the current value of the property you are trying to animate.

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

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

Tween Object Collections

The two new methods allow you to create animations for multiple HTML elements at the same time, all in a single line of code. They use the above methods to create a tween object for each element of the collection and also enable the tween control methods in this new context.

.allTo() method allows you to create an array of tween objects for a collection of elements. This method is using the above .to() method and inherits it's functionality. Considering a given collection myDivs elements, a nice example would be:

// on the fly, grab the elements by className,
// do the tween objects array, and start kicking
KUTE.allTo( '.my-div-class', {opacity:1}, {offset: 200, duration: 500} ).start();

// or we cache the objects for better performance and / or later control
var myDivs          = document.querySelectorAll('.my-div-class');
var myDivsTweens    = KUTE.allTo( myDivs, {opacity:1}, {offset: 200, duration: 500} );

.allFromTo() method is also a method to animate a collection of elements and it uses the .fromTo() method. Quick example:

KUTE.allFromTo( myDivs, {opacity:1}, {opacity:0}, {offset: 200, duration: 500} ).start()

As you can see the above code, these methods have a specific tween option called offset that allows you to set a delay in miliseconds between the starting time of each tween animation. Most tween control methods apply to both methods, except for the .chain() method. In order to chain another tween to one of the myDivsTweens objects, we would need to access it from the array, but let's leave that for later.

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. This method also applies to arrays of tween objects created with .allTo() and .allFromTo() methods.

//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

// lastly the method works with tweens made with .allTo() and .allFromTo() methods
KUTE.allFromTo(divs,{opacity:1},{opacity:0}).start();
KUTE.allTo(divs,{opacity:0}).start();

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 on animations start, even if you are using the .to() method. The trick is super duper simple:

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

// 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);
}

In other cases the new methods .allTo() and .allFromTo() can be more useful.

Stopping Animation

.stop() method stops animation for a given tween object or an array of tween objects (built with .to()/.fromTo() methods) 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:

// for a tween object
stopButton.addEventListener('click', function(){
  myTween.stop(); // myMultiTweens.stop();
}, false);

Pausing Animation

.pause() method freezez the animation at any given time for a given tween object or collection, 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(); // or myMultiTweens.pause();
}, false);

Resuming Paused Animation

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

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

Chaining Tweens

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

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.

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

Another thing we talked before is the ability to chain to one of the tween object within the array built with .allTo() or .allFromTo() methods.

// chain to a tween from collection
var tweensCollection = KUTE.allTo('.a-class-for-multiple-elements', {opacity: 1});

// considering the collection has 5 tweens,
// the array is right here tweensCollection.tweens, so
// let's grab the second and chain another tween to it
tweensCollection.tweens[1].chain(tween2);

Also we can chain the tweens created with .allTo() and .allFromTo() methods like this:

// chain a collection of tweens to another tween
var tweensCollection2 = KUTE.allTo('.a-class-for-multiple-elements', {opacity: 1});

// the array is right here tweensCollection2.tweens
// we can pass it in the chain of another tween
tween2.chain(tweensCollection2.tweens);