A JavaScript tween'ing script

Tween'ing your Animations


This script provides tweening to your animations using RAF. A tween is defined by a duration time length over which a value will transition successively from a start value to an end value. This script will calculate the current value of a property, between a pair of end point values, over time, upto a duration length of time.

This script works on all modern browsers including IE9 and above.


This script depends on and includes the timer T{} script. If you are using this Tween object for your animations, you will not need to use timer T{} object directly. If you already have the timer T{} included in your program, be sure to delete it from this script.

What is Tweening?

Tweening provides great power to animation programming. The word tweening is a play on the phrase "in between" and refers to calculating points in between two end points with time. A Time zero corresponds to the start value and the end value corresponds to when the full duration of time has past.


Instantiate a Tween instance with the arguments: start_value, end_value, and time_duration. Begin the tweening by calling the init() method, passing in the object you wish to animate.

The object you wish to animate must be designed and coded to include a setPosition() method and a done() method. The setPosition() will be called by Tween successively upon timing T{} ticks(). Where as timing T{} RAF tick() method calls are passed the elapsed time between frame, the Tween object will use the elapsed time to calculate the current position for you and pass the result to the animating object's setPosition() method.

Usage Example

Consider the following red box of size 100X100px with a margin-left value of 100px, inside a wrapper div that is 600px wide. Suppose we wish to animate the margin-left property from 100→400px over 5secs(5000ms).

Instantiating a Tween object:

var redTW = new Tween();

We would need to prepare an object with a setPosition() method and a done() method and pass that object to the init() method such as the following:

var myTweenObj = { redDiv:document.getElementById("redDiv"), setPosition:function(position){}, // updates/ticks this.redBox.style.marginLeft = position + "px"; }, done:function(){ // animation is done } };

Now to configure your Tween object with the start value, end value, duration and the object you have prepared for animation.

redTW.config(100, 400, 5000, myTweenObj);

Result: 0/5000, 0%, margin-left: 100px


If you want the animation to continuously loop, call reset() & play() in the done() method.

done:function(){ // animation is done redTW.reset(); redTW.start(); }

Result(Looping): 0/5000, 0%, margin-left: 100px


If you want the animation to go back and forth reversing each time it complete, re-configure the Tween object in the done() method with the start and end values reversed.

endpoints:[100,400], done:function(){ // animation is done this.endpoints.reverse(); redTW.config( this.endpoints[0], this.endpoints[1], 5000, this ); redTW.reset(); redTW.start(); }

(Reversing): 0/5000, 0%, margin-left: 100px

Final Notes

Tween.js & Tween.min.js download file links are of a small file size. Tween.js is just a few lines. And so to reduce the number of file gets() your web page requires, I would advise to just copy-paste the code in with the rest of your JavaScript.

The minified script was minified using the closure compiler with the Optimization level set to (O)Whitespace only, and all formatting options unchecked.

This page and all it contents are also posted at the following github link: github.com/nadeemelahi/tween.


gpl v3

Free for personal or business use.
Source code is included -no obfuscation.
Not for re-sale.


(same as top of page)

Tween.js Tween.min.js

Copyright 2024 © nadeem.elahi@gmail.com | nad@3deem.com