Tweene

Documentation

Getting Started

To start using Tweene just include the script after your animation library of choice. 

// use Tweene with GSAP
<script src="/your/path/TweenMax.min.js"></script>
<script src="/your/path/tweene-gsap.min.js"></script>

// use Tweene with jQuery
<script src="/your/path/jquery.min.js"></script>
<script src="/your/path/tweene-jquery.min.js"></script>

// use Tweene with Transit
<script src="/your/path/jquery.transit.js"></script>
<script src="/your/path/tweene-transit.min.js"></script>

// use Tweene with Velocity.js
<script src="/your/path/velocity.min.js"></script>
<script src="/your/path/tweene-velocity.min.js"></script>

// use Tweene with more then one library
<script src="/your/path/TweenMax.min.js"></script>
<script src="/your/path/jquery.transit.js"></script>
<script src="/your/path/velocity.min.js"></script>
<script src="/your/path/tweene-all.min.js"></script>
<script>
	// set the default time unit you want to use
	Tweene.defaultTimeUnit = 'ms'; // or 's'
	
	// set the default driver you want to use
	Tweene.defaultDriver = 'gsap'; // or one of 'transit', 'velocity', 'jquery'
</script>

Or with package managers:


bower install tweene
or
npm install tweene

// use Tweene with more then one library
require('tweene');  

// use Tweene with GSAP
require('tweene/gsap');

// use Tweene with jQuery
require('tweene/jquery');

// use Tweene with Transit
require('tweene/transit');

// use Tweene with Velocity.js
require('tweene/velocity');

Time unit

Tweene tries to accommodate your current programming habits, not to force you to change them. For this reason, you can configure the default time unit used to indicate durations and delays of your tweens, by changing the value of Tweene.defaultTimeUnit (accepted value: 's' or 'ms').
Since the GSAP library uses natively seconds as time unit, when you will use only that specific driver through tweene-gsap.min.js or require('tweene/gsap') please note that the predefined value of Tweene.defaultTimeUnit will be 's'. In all other cases, it defaults to 'ms'.
However, you can change it any time you want and also on a single call basis.
Check "Duration" for more details.

Create a tween

The tween is the object the allows you to animate specific properties of a chosen target. A target could be a single DOM element or a collection of elements. The nature of the target object depends from the animation library of your choice. Commonly it would be a jQuery object, and we assume this as default behavior in this documentation and in our examples.

With Tweene you will never need to instantiate tweens or timelines with the new operator. You have to use one of the static methods available.
The basic way for create a tweene is with the get operator: 

var tween = Tweene.get($target);

This will create a tween object using the default driver. If you want to create a tween that uses a different animation library - assuming you are usign the full version of Tweene and you have all the libraries linked in your page - you can obtain it passing the driver name as the second parameter: 

var velocityTween = Tweene.get($target1, 'velocity');
var gsapTween = Tweene.get($target2, 'gsap');
var transitTween = Tweene.get($target3, 'transit');

The important thing to remember about tweens created with get() method is that they are paused by default, in order to allow you to specify all the needed options before starting it manually with play() method.
So far we have created a tween but it is not doing anything yet. Let's see how to proceed.

Animate to...

Any animation requires at least one set of CSS properties that we want to change. The to() method allow the most common animation in which we specify the final state of the properties. Let's see all the different syntax allowed by Tweene to obtain this.
We want to fade-out the target element while moving its horizontal position. We assume that the default time unit is milliseconds and a duration of 500ms. We specify also an easing and a complete callback. 

var completeCallback = function() {
    console.log('just finished');
};

// jQuery syntax style:
Tweene.to($target, {opacity: 0, left: '+=50px'}, 500, 'easeOutQuad', completeCallback);

// GSAP syntax style, duration in seconds passed before properties, 
//all options passed inside the properties object:
Tweene.to($target, '0.5s', {opacity: 0, left: '+=50px', ease: 'easeOutQuad', onComplete: completeCallback});

// Velocity.js syntax style, options grouped in an object passed as second parameter:
Tweene.to($target, {opacity: 0, left: '+=50px'}, {duration: 500, easing: 'easeOutQuad', complete: completeCallback});

// single object syntax, as allowed by Transit:
Tweene.to($target, {opacity: 0, left: '+=50px', duration: 500, easing: 'easeOutQuad', complete: completeCallback});

// Fluent syntax:
Tweene.get($target)
    .to({opacity: 0, left: '+=50px'})
    .duration(500)
    .easing('easeOutQuad')
    .on('complete', completeCallback)
    .play();                                    // tweens created with get() need to be started manually

// alternative syntax:
Tweene.get($target)
    .to({opacity: 0, left: '+=50px'})
    .options({duration: '500ms' easing: easeOutQuad', complete: completeCallback})
    .play();                                    

// whatever mix of syntax you like, this is just an example:
Tweene.get($target)
    .to({opacity: 0, left: '+=50px', easing: 'easeOutQuad'}, 500)
    .on('complete', completeCallback)
    .play();

If you want to create a tween with to() that will not start immediately, just set the paused option:

var t = Tweene.to($target, {opacity: 0}, {duration: 500, paused: true});
// later, modify the previously set duration and run:
t.duration(300).play();

Animate from...

With Tweene you could do also a "from animation", meaning you could specify the beginning values of the target's properties, while the current values are assumed as the ending of the animation. Currently only GSAP library offers this feature natively, but with Tweene you can do it with all other supported libraries too. Let's see a fade-in effect, assuming that the current value of target's opacity is 1:

// jQuery syntax style:
Tweene.from($target, {opacity: 0}, 500);

// GSAP syntax style:
Tweene.from($target, '0.5s', {opacity: 0});

// Velocity.js syntax style
Tweene.from($target, {opacity: 0}, {duration: 500});

// single object syntax
Tweene.from($target, {opacity: 0, duration: 500});

// Fluent syntax:
Tweene.get($target)
    .from({opacity: 0})
    .duration(500)
    .play();

Animate from... to

Using both from and to options you could achieve full control of both initial and final animated properties' value. This is also equivalent to the forcefeeeding technique used in Velocity.js to define properties start value.
Let's define a transition of target's opacity from 0 to 1: 

// jQuery syntax style:
Tweene.fromTo($target, {opacity: 0}, {opacity: 1}, 500);

// GSAP syntax style:
Tweene.fromTo($target, '0.5s', {opacity: 0}, {opacity: 1});

// Velocity.js syntax style
Tweene.fromTo($target, {opacity: 0}, {opacity: 1}, {duration: 500});

// Fluent syntax:
Tweene.get($target)
    .from({opacity: 0})
    .to({opacity: 1})
    .duration(500)
    .play();

// Mixed syntax example:
Tweene.get($target)
    .from({opacity: 0})
    .to({opacity: 1}, 500)
    .play();

Set properties instantly

Sometimes you need to change some properties instantly without any tween. You can do it with set() method: 

Tweene.set($target, {left: 100, top: 200});
// using get and set:
Tweene.get($target).set({left: 100, top: 200});
// setting properties with another library:
Tweene.get($target, 'gsap').set({left: 100, top: 200});

Properties Syntax

Every animation libraries has its own specific dialect for some CSS transform properties. For example with GSAP and Transit you could define a 2D translation using x and y while Velocity.js needs translateX and translateY. GSAP uses rotation, Velocity.js accepts rotateZ, Transit accepts rotate, and so on. Tweene takes care of this thing for you, accepting a wide range of different names and replacing them accordingly to those accepted by the library currently used.

Moreover, Tweene accepts also property names passed with dashed CSS syntax like padding-top or margin-left, translating them to camelCase syntax accepted by any library.

Compound properties

Only GSAP and Transit have native support for direct compound properties like padding, margin and so on (Velocity.js has a partial support because accept them only in the form with a single value like: padding: '2px').
With Tweene you could use from 1 to 4 space-separated values with this set of properties (the support will be extended to other properties in next releases):

  • margin
  • padding
  • borderColor
  • borderWidth
  • borderRadius

These are all valid statements with Tweene:

Tweene.set($target, {padding: '2px 2em 5px 0'});
Tweene.set($target, {margin: '10px auto'});

Display & Visibility

As some supported libraries already do, Tweene handles display and visibility CSS properties in a different way:
"none" value for display and "hidden" value for visibility will be applied to the target just after the tweening, while any different value for both properties will be applied immediately before the tweening. 

Tweene.set($target, {display: 'none', opacity: 0});

// apply the display value, then run the tween
Tweene.to($target, {display: 'block', opacity: 1}, 500);

// run the tween, then apply the visibility value
Tweene.to($target, {visibility: 'hidden', opacity: 0}, 500);

Tween Options

Target

An important feature of Tweene is that all options, properties values, event handlers and so on can be changed as you wish before the tween start its animation. This is true also for the tween's target. 

var tween = Tweene.get($('#box1').to({opacity: 0.5});

// replace the target, set the duration and run:
tween
    .target($('#box2'))
    .duration('2s')
    .play();

Then

With Tweene's then option you can define a set of properties to be applied just after the end of the tween's animation. 

Tweene.get($target)
    .from({x: 0, y: 0, opacity: 0.5})   // define initial state
    .to({x: 300, y: 200})               // define final state
    .then({opacity: 1, scale: 1.5})     // apply instantly after tween's end
    .duration(400)                      // define duration
    .play();                            // run!

// same result, different syntax
Tweene.fromTo(
    {x: 0, y: 0, opacity: 0.5},
    {x: 300, y: 200},
    {duration: 400, then: {opacity: 1, scale: 1.5}}
);

Duration

You can define tween's duration in four different ways:

  • As a number, it is interpreted accordingly with Tweene.defaultTimeUnit that could be "s" (seconds) or "ms" (milliseconds)
  • As string made by a number followed by the time unit: "0.5s", '350ms'
  • As a string that refers to a duration constant defined in Tweene.durations object. It comes prefilled with these two constant: 'fast': '200ms' and 'slow: '600ms', obviously you are free to extend it with your favourite key - value pairs
  • Without passing any value, every tween has a default duration defined in Tweene.defaultDuration, its value is "400ms",
// duration = Tweene.defaultDuration = 400ms
Tweene.to($target, {opacity: 0.3});

// duration = 200ms, passed before properties object
Tweene.to($target, 'fast', {opacity: 0.3});

// duration passed after properties object, defined as number, unit in Tweene.defaultTimeUnit
Tweene.to($target, {opacity: 0.3}, 500);

// duration defined with time unit in options object 
Tweene.to($target, {opacity: 0.3}, {duration: '0.5s'});

// duration defined with fluent syntax
Tweene.get($target)
    .to({opacity: 0.3})
    .duration('500ms')
    .play();

Easing

With Tweene you can define the easing function passing one of these predefined string:
'linear', 'ease', 'ease-in', 'ease-out', 'ease-in-out', 'in', out, 'in-out', 'snap', 'easeInCubic', 'easeOutCubic', 'easeInOutCubic', '-easeInCirc', 'easeOutCirc', 'easeInOutCirc', 'easeInExpo', 'easeOutExpo', 'easeInOutExpo', 'easeInQuad', 'easeOutQuad', 'easeInOutQuad', 'easeInQuart', 'easeOutQuart', 'easeInOutQuart', 'easeInQuint', 'easeOutQuint', 'easeInOutQuint', 'easeInSine', 'easeOutSine', 'easeInOutSine', 'easeInBack', 'easeOutBack', 'easeInOutBack'.
These easing functions ensure the same behavior in all the supported libraries, in order to make easier to switch from one library to another.
The default easing function is defined in Tweene.defaultEasing and currently its value is 'easeOutQuad'.

Alternatively, you can define the easing passing an array of four values which represents a cubic bezier curve. You could easily find these values using some tools like Cubic-bezier.com.

Important note: only using cubic bezier easing functions (those predefined with a name shortcut are included) Tweene guarantees to implement pause() / reverse() and resume() commands that honor the expected easing ratio for all the libraries that lacks native support for these commands (Only GSAP support them natively).
This means that you are free to pass another kind of easing function supported natively by the used library (for example a 'spring' easing in Velocity.js or one of the custom easing function defined by jQueryUI or by by any plugin), but in such cases the behavior of control commands will not be able to ensure the right and expected easing ratios. 

// easing defined with jQuery style syntax
Tweene.to($target, {opacity: 0.3}, 500, 'easeOutBack');

// easing defined with GSAP style syntax as cubic bezier curve
Tweene.to($target, 500, {opacity: 0.3, ease: [.39, .575, .565, 1]});

// easing defined in options object
Tweene.to($target, {opacity: 0.3}, {duration: 500, easing: 'easeOutBack'});

// easing defined with fluent syntax as cubic bezier curve
Tweene.get($target).to({opacity: 0.3}).duration(500).easing([.42, 0, .58, 1]).play();

Macro

With Tweene you can register macro functions in order to define commonly used animations.
Inside defined macro function, this will refer to the tween object.
Macro execution is performed with exec() method and you can also schedule them inside timeline like any other tween. 

// register macro functions
Tweene.registerMacro('fadeIn', function(){
    this.to({opacity: 1, display: 'block'});
});

Tweene.registerMacro('slideUp', function(duration){
    this
        .to({top: '-=100', opacity: 0})
        .duration(duration || Tweene.defaultDuration);
});

// exec macro
Tweene.get($target).exec('fadeIn').play();
Tweene.get($target).exec('slideUp', '800ms').play();

// schedule macro inside a timeline
Tweene.line()
    .to($target, {left: 500}, '2s')
    .exec($target, 'slideUp')
    .play();

Create a timeline

Without timeline tools it is really hard to organize complex sequences of tweens:

  • with native queue you can make only a non-overlapping sequence of tweens related to a single target, you are unable to sequence tweens of different elements
  • The only way for sequence tweens of different elements is to deeply nest inside complete callbacks
  • if a "one after the other" sequence is not enough for your needs, you can rely only on delays, that are really hard to mantain in sequences that involve more than just two or three tweens.

Tweene offers fully featured Timelines to all supported libraries (currently only GSAP has native support for them) allowing you to organize complex sequences of tweens and also nested timelines in the easiest way.
Let's see how to create a timeline: 

// create an empty timeline
var t = Tweene.line();

// create a timeline with options:
var t = Tweene.line({delay: '2s', loops: 2});

// create a timeline and set options with fluent syntax:
var t = Tweene.line()
    .delay('2s')
    .loops(2);

// create a dedicated timeline for the specified target:
var t = Tweene.line($('#box1'));

// create a dedicated timeline for the specified target, with options:
var t = Tweene.line($('#box1'), {delay: '500ms'});

Add tweens to a timeline

With add() method you can insert tweens, other timelines, callbacks and labels in a timeline.
The basic syntax is add(objectToAdd [, position]). Let's see how position param works: 

// create some tweens 
var child1 = Tweene.get($('#box1').to({opacity: 0}, 500);
var child2 = Tweene.get($('#box2').to({left: '+=50'}, '0.5s');
var child3 = Tweene.get($('#box3').fromTo({top: 10}, {top: 100}, 600, 'easeInBack');

// create the timeline
var t = Tweene.line();
t
    // add the tween to the end of the timeline, currently 0
    .add(child1)            

    // add the tween to an absolute position in the timeline, now timeline's global duration is 0.7s
    .add(child2, 200)       

    // add the tween shifting to the end of timeline plus 150ms, so at 850ms
    .add(child3, '+=150');  

// other examples
var t = Tweene.line()

    // insert a label 
    .add('myLabel', '2.5s')         
    
    // add the tween to label position plus 200ms
    .add(child1, 'myLabel+=200')    
    
    // add the tween to the beginning of the timeline
    .add(child2, 0)
    
    // add the tween in a relative position to the last inserted tween (child2) regardless the current timeline duration
    .add(child3, '++=200');

You can use the same syntax for adding child timelines instead of single tweens.

Add tween to a timeline with to() method

This method is a convenient way for adding Tweene.to() kind of tweens.
Important: if you want to set an explicit position inside the timeline, you cannot rely on implicit default tween's duration, you have to pass both parameters. 

// insert a tween at 700ms, long way:
var t = Tweene.line().add(Tweene.get($('#box1')).to({opacity: 0.5}, 500), '700ms');

// insert a tween at 700ms, shorter way:
var t = Tweene.line().to($('#box1'), {opacity: 0.5}, 500, '700ms');

// insert tweens in a dedicated timeline:
var t = Tweene.line($('#box1'))
    .to({opacity: 0.5}, 500, '700ms')
    .to({left: '+=200'}, 300, '+=150');

Add tween to a timeline with from() method

This method is a convenient way for adding Tweene.from() kind of tweens.
Important: if you want to set an explicit position inside the timeline, you cannot rely on implicit default tween's duration, you have to pass both parameters. 

// insert a tween at 700ms, long way:
var t = Tweene.line().add(Tweene.get($('#box1')).from({opacity: 0.5}, 500), '700ms');

// insert a tween at 700ms, shorter way:
var t = Tweene.line().from($('#box1'), {opacity: 0.5}, 500, '700ms');

// insert tweens in a dedicated timeline:
var t = Tweene.line($('#box1'))
    .from({opacity: 0.5}, 500, '700ms')
    .to({left: '+=200'}, 300, '+=150');

Add tween to a timeline with fromTo() method

This method is a convenient way for adding Tweene.fromTo() kind of tweens.
Important: if you want to set an explicit position inside the timeline, you cannot rely on implicit default tween's duration, you have to pass both parameters. 

// insert a tween at 700ms, long way:
var t = Tweene.line().add(Tweene.get($('#box1')).fromTo({opacity: 1}, {opacity: 0.5}, 500), '700ms');

// insert a tween at 700ms, shorter way:
var t = Tweene.line().fromTo($('#box1'), {opacity: 1}, {opacity: 0.5}, 500, '700ms');

// insert tweens in a dedicated timeline:
var t = Tweene.line($('#box1'))
    .fromTo({opacity: 1}, {opacity: 0.5}, 500, '700ms')
    .from({top: 0}, 300)
    .to({left: '+=200'}, 300, '+=150');

Add an instant tween to a timeline with set() method

You can also insert instant tweens (equivalent to a Tweene.to() with duration = 0) inside timelines: 

// insert a tween, then change instantly its target's properties 500ms later:
var $target = $('#box1');
var t = Tweene.line()
    .to($target, {opacity: 0.5}, 300))
    .set($target, {left: 100, top: 100}, '+=500');

// same result, with a dedicated timeline:
var t = Tweene.line($target)
    .to({opacity: 0.5}, 300))
    .set({left: 100, top: 100}, '+=500');

Nesting timelines in timelines


// first child timeline
var t1 = Tweene.line()
    .to($('#box1'), {opacity: 1}, 1500)
    .to($('#box2'), {left: 100}, 400, 100)
    .to($('#box3'), {left: '+=200'}, 400, '++=0');

// second child timeline
var t2 = Tweene.line($('#box4'))
    .to({opacity: 0.2}, 500)
    .to({left: 200}, '1.5s')
    .to({left: '+=300'}, 400);

// nesting timelines inside a parent timeline
var t = Tweene.line()
    .add(t1)
    .add(t2, '+=1s')
    .play();

Labels

Labels are a convenient way to save some specific positions in a timeline, in order to refer to them for position other elements.
A label identifier need to start with an alphabetic character.

var t1 = Tweene.line()
    .add('myLabel1', 500)                           // set a label at position 500
    .add('myLabel2', 'myLabel1-=200')               // set a label relative to another label's position
    .to($('#box2'), {left: 100}, 400, 'myLabel2');  // add a tween on a previously stored position

Callbacks

You can add function callbacks inside timelines at absolute or relative positions like any other child tween or timeline.
The function will be called every time the timeline playhead will be at that position. You can also define an additional array of parameters and the scope (the object referred as this inside the function's body). If you don't specify any scope, it will refers to the parent timeline.
add(callback [, position [, params [, scope]]]) 

var t = Tweene.line();

// add a simple callback at an absolute position
t.add(function() { console.log('half second here'); }, '0.5s);

// add a callback with params at the end of the timeline
t.add(function(a, b, c) { console.log('params: ', a, b, c); }, null, ['aaa', 'bbb', 15.8]);

// add a callback with params and scope in a relative position
var $target = $('#box1');
t.add(function(a, b, c) { 
        console.log('params: ', a, b, this.outerWidth()); 
    }, 
    '+=2s', 
    ['aaa', 'bbb', 15.8], 
    $target
);

Directional Callbacks

With Tweene you can also define callbacks that will be fired only when the parent timeline is running in forward or backward direction, passing respectively 1 or -1 as first parameter. 

var t = Tweene.line();

t.add(function() { console.log('I run in both direction'); });

t.add(1, function() { console.log('I run only in forward direction'); });

t.add(-1, function() { console.log('I run only when timeline is reversed'); });

Tween & Timeline options

Here you can find a list of options and commands that apply both for tweens and timelines.

Delay

You can define a delay before the start of a tween or timeline. The element will wait for the delay only on the first execution. If you call a restart() on that element it will run immediately, ignoring the initial delay.
Please note that in case of from or fromTo tweens, also the setting of the initial (from) state will be delayed accordingly. For GSAP users: this means that Tweene runs always with implicit immediateRender: false. You can easily achieve the same result of an immediate render scheduling a set() just before the delay. 

// setting tween delay 
Tweene.to($target, {opacity: 0}, {duration: 500, delay: 200});
Tweene.get($target).to({opacity: 0}).duration(500).delay('0.2s');
Tweene.get($target).to({opacity: 0}).options({duration: 500, delay: '200ms'});

// setting timeline delay 
Tweene.line({delay: 200});
Tweene.line().delay('0.2s');
Tweene.line().options({delay: '200ms'});

Loops

With loops you can iterate your tweens and timelines an arbitrary amount of times.
Note that when loops = 0 the animation run once, so loops = 1 means that the animation will run twice, and so on.
Infinite loops can be achieved setting loops to -1.

Important: please note that an infinite looping tween or timeline will have infinite duration accordingly, so if you add it to a timeline, that timeline will have infinite duration too, then adding other children to a position relative to the parent timeline duration will result in those children never executing, because their start position will be clearly equal to Infinity. In order to avoid this, you have to position other children at absolute positions or relative positions to labels or finite duration children. 

// tween will run four times
Tweene.to($target, {opacity: 0}, {duration: 500, loops: 3});

// tween will run in infinite loop
Tweene.get($target).to({opacity: 0}).duration(500).loops(-1);

// timeline will repeat twice ('repeat' is an alias for loops option)
Tweene.line({repeat: 1});
Tweene.line().loops(1);

Loops Delay

With loopsDelay option you could set any amount of delay between each loop iteration.
Clearly this option makes sense only when you have a loops value different from 0. 

// setting tween loopsDelay
Tweene.to($target, {opacity: 0}, {loops: 2, loopsDelay: 200});
Tweene.get($target).to({opacity: 0}).loops(2).loopsDelay('0.2s');
// you can use also repeat and repeatDelay as alias
Tweene.get($target).to({opacity: 0}).options({repeat: 2, repeatDelay: '200ms'});

// setting timeline loopsDelay 
Tweene.line({loops: 2, loopsDelay: 200});
Tweene.line().loops(2).loopsDelay('0.2s');
Tweene.line().options({loops:2, loopsDelay: '200ms'});

Yoyo effect

Along with loops option, you can enable Yoyo effect by setting yoyo option to true:
the animation will change direction between forward and backward on each loop iteration. 


Tweene.to($target, {opacity: 0}, {loops: 2, loopsDelay: 200, yoyo: true});
Tweene.get($target)
    .to({opacity: 0})
    .loops(2)
    .loopsDelay('0.2s')
    .yoyo(true);

Tweene.line({loops: 2, loopsDelay: 200, yoyo: true});
Tweene.line().loops(2).loopsDelay('0.2s').yoyo(true);

Speed Control

With Tweene you can change dinamically the speed of tweens and timelines, both before they start and during their run, in order to achieve great looking effects like slow-motion and fast-forward. You can define the speed as a float number (1 = normal speed, 2 = double speed = half duration, 0.5 = half speed, double duration and so on), or pass one of the predefined shortcuts set in Tweene.speeds object. It comes prefilled with values 'half' and 'double', but you are free to extend it with your values of choice. 

// set speed statically before the tween start:
Tweene.to($target, {opacity: 0}, {duration: 2, speed: 0.7});

var t = Tweene.get($target)
    .to({opacity: 0})
    .duration('5s')
    .play();

// during the tweening, slow down
t.speed('half');

var t = Tweene.line($target)
    .to({opacity: 0})
    .duration('5s')
    .play();

// go fast forward using the timeScale alias
t.timeScale(3.5);

Tween & Timeline Controls

Tweene gives you the commands for achieve full control of your animation pausing, resuming, reversing and restarting it every time you want. Let's see each command in details.

Play

Play command run the tween or timeline from its current position in forward direction. If the animation is currently playing reversed, play() will change its direction to forward. 

// start a tween
var t = Tweene.to($target, {opacity: 0}, {duration: 2, paused: true});
t.play();

var t = Tweene.get($target)
    .to({opacity: 0})
    .duration('5s')
    .play();

// start a timeline
var t = Tweene.line($target)
    .to({opacity: 0})
    .duration('5s')
    .play();

Pause

Pause command halt a running tween or timeline in its current position. If the animation is already paused (or not yet started) it has no effect.

Reverse

Reverse command run the tween or timeline from its current position in backward direction. If the animation is at ts starting position, reverse() will not have any effect. The same apply calling play() on an animation that has already reached its final position.

Resume

Resume command resume the run of a paused (or not yet started) tween or timeline without altering its current direction.

Restart

Restart command reset the tween or timeline position and loops counter and play it in forward direction, whatever is its current position, direction and state.

Tween & Timeline Events

Tweene timelines and tweens come with a full stack of events that allow you to define your callbacks in key points of the animation or perform some custom code during the whole progress of the application.
Important things to know about events:

  • Events are fired only ones per tween / timeline object, regardless the amount of DOM elements referred as targets of the animation
  • As for timeline callbacks, you can define additional parameters and a scope for the callback
  • If you do not define a scope, this will refer to the tween / timeline object inside your callback. Then you can easily access your animation target with this.target()
  • Every event has a list of aliases in order to cover most of the habits and conventions

Let's see some example on how to set events callback and additional parameters. This syntax apply to every events available. 

// setting a simple begin callback 
var t = Tweene.get($target)
    .to({opacity: 0})
    .duration(500)
    .on('begin', function() { console.log('starting'); })
    .play();

// setting a complete callback with params and scope
var t = Tweene.get($target)
    .to({opacity: 0})
    .duration(500)
    .on('complete', function(a, b) { console.log('completed: ', a, b, this.attr('id')); }, [3, 'bye'], $target)
    .play();

// setting the same complete callback with different syntax
var t = Tweene.to($target, '500ms', {
    opacity: 0, 
    onComplete: function(a, b) { console.log('completed: ', a, b, this.attr('id')); }, 
    onCompleteParams: [3, 'bye'], 
    onCompleteScope: $target
});

// setting progress event on a timeline
var t = Tweene.line($target).to({opacity: 0}, {duration: '500ms', progress: function() { console.log('we are making progress here'); }});

Begin Event

Begin event fires at the start of the tween / timeline animation. If you have set a delay, begin event will fire after the delay. It will not fire on loop iterations.
Aliases: begin, onBegin, start, onStart.

Complete Event

Complete event fires at the end of the tween / timeline animation that is running in forward direction. It will not fire at the end of intermediate loop iterations, just at the very end of the animation. This imply that if you have set an infinite loop, complete event will never raise.
Aliases: end, complete, onEnd, onComplete, finish, onFinish, done.

Reverse Event

Reverse event is the counterpart of Complete event for backward direction, so it fires at the end of the tween / timeline animation that is running backward. It will not fire at the end of intermediate reversed loop iterations.
Aliases: reverse, onReverse, onReverseComplete.

Loop Event

Loop event fires at the end of each loop iteration with the exclusion of the last, that will fire instead a Complete or Reverse event accordingly with current direction.
Aliases: loop, onLoop, onRepeat.

Progress Event

Progress event fires continuously during the tween / timeline animation. If you have loops with loopsDelay set, it will fire also during loops delay. It does not fire if the animation is paused.
The event implementation relies on library's native progress event if available, or it is emulated by Tweene if it's not present natively, so you could expect different frequencies of the progress event for different libraries used.
Aliases: progress, onProgress, update, onUpdate.

Demos