tween.js

tween.js (r15dev)

JavaScript tweening engine for easy animations

Install with NPM: npm install tween.js

Super simple, fast and easy to use tweening engine which incorporates optimised Robert Penner's equations.

Contributors

Examples

source source source source source source source source source source source source source

Projects using tween.js

Getting it

Download the library and include it in your code:

<script src="js/Tween.js"></script>

More advanced users might want to...

Use npm

npm install tween.js

Then include the Tween.js module with the standard node.js require:

var TWEEN = require('tween.js');

And you can use Tween.js as in all other examples--for example:

var t = new TWEEN.Tween( /* etc */ );
t.start();

You will need to use a tool such as browserify to convert code using this style into something that can be run in the browser (browsers don't know about require).

Use bower

bower install tweenjs

or install an specific tag. They are git tags, and you can run git tag for a list:

bower install tweenjs#r14

Then reference the library source:

<script src="bower_components/tween.js/src/Tween.js"></script>

Usage

The following code creates a Tween which will change the x attribute in a position variable, so that it goes from 50 to 400 in 2 seconds. We'll use requestAnimationFrame to call TWEEN.update so that "time ticks", the tween gets updated and the onUpdate method makes things happen on the screen:

	init();
	animate();

	function init() {

		var output = document.createElement( 'div' );
		output.style.cssText = 'position: absolute; left: 50px; top: 300px; font-size: 100px';
		document.body.appendChild( output );

		var tween = new TWEEN.Tween( { x: 50, y: 0 } )
			.to( { x: 400 }, 2000 )
			.easing( TWEEN.Easing.Elastic.InOut )
			.onUpdate( function () {

				output.innerHTML = 'x == ' + Math.round( this.x );
				var transform = 'translateX(' + this.x + 'px)';
				output.style.webkitTransform = transform;
				output.style.transform = transform;

			} )
			.start();

	}

	function animate(time) {

		requestAnimationFrame( animate ); // js/RequestAnimationFrame.js needs to be included too.
		TWEEN.update(time);

	}

Note: this corresponds to the example 04_simplest.html that you can find in the examples folder.

Have a look at that folder to discover more functionalities of the library, or read the user guide!

Also, Jerome Etienne has written a tutorial demonstrating how to use tween.js with three.js, and it's also great for understanding how tweens work!

Finally, if you need to use tweens in C/C++ code, you now have an option! Check out libtween which is a port of tween.js to C by jsm174!

Running the tests

You need to install npm first--this comes with node.js, so install that one first. Then, cd to tween.js's directory and run:

npm test

If you want to add any feature or change existing features, you must run the tests to make sure you didn't break anything else. If you send a PR to add something new and it doesn't have tests, the PR won't be accepted (unless it's seriously good). See contributing for more info.

Change log

2015 09 29 - r16

• Remove the minified version and the build folder. From now on we just publish and refer to the code in src/Tween.js (sole).

2015 07 17 - r15

• Better bower.json support (azachar)
• Better module support and add performance.now polyfill (superlukas)
• Cleaning up various things that are pointing to wrong places, etc (sole)

2014 06 15 - r14 (5,798 KB, gzip: 2,168 KB)

• Include license header on the minified files too (hyandell)
• Make examples more efficient by using requestAnimationFrame's own timer instead of calling Date.now again (Robert Eisele)
• Make it explicit that you can install tween.js with npm and bower (sole)

2014 05 05 - r13 (5,765 KB, gzip: 2,149 KB)

• Add Tween.onStop (colinsullivan)
• Fix _reversed yoyo flag bug (deanm)
• Initial version of docs/user guide (sole)

2013 11 03 - r12 (5,697 KB, gzip: 2,131 KB)

• Fix bug with cached tweens.length value inside update() loop (freestlr)
• Move assets and all examples and stuff to use the gh-pages branch, so things are always properly updated (sole).
• Fix bug where chained tweens were not stopped if the previous tween had been stopped, under certain circumstances, by fundon
• Use tweens in C/C++ with libtween by jsm174!

2013 08 10 - r11

• Add yoyo functionality: tweens can bounce back to their original value when finished (benjamind)
• Make tween.js an official npm module (sole) (hint: npm install tween.js)
• Bring node.js compatibility back! (benjamind)
• Bring IE shim back! (sole)
• Tween only strings, arrays or numbers (JAStanton)

2013 03 03 - r10 (5,342 KB, gzip: 2,010 KB)

• Added the ability to tween using relative values with to() (endel)

2013 02 04 - r9 (5,224 KB, gzip: 1,959 KB)

• Use window.performance.now() if available for even smoother animations (tdreyno, mrdoob and sole)
• Added tween.repeat() (sole)
• Improve example_01 performance (mrdoob)
• Use CONTRIBUTING.md instead of having the section on README.md (sole)

2013 01 04 - r8 (4,961 KB, gzip: 1,750 KB)

• New Date.now() shim by roshambo makes the lib compatible with IE
• Fix for checking undefined duration (deanm)
• Add unit tests (sole)
• Fixed non-existing properties sent in to and ending up as NaN in the target object (sole)
• Add missing example screenshot (sole)
• Add CONTRIBUTING section in README (sole)

2012 10 27 - r7 (4,882 KB, gzip: 1,714 KB)

• Fixed start time of chained tweens when using custom timing. (egraether)
• TWEEN.update() now returns a boolean (tweens pending or not). (mrdoob)
• Added tween.onStart(). (mrdoob)
• tween.chain() now accepts multiple tweens. (mrdoob)

2012 04 10 - r6 (4,707 KB, gzip: 1,630 KB)

• Returning instance also in .chain(). (mrdoob)
• Refactoring and code clean up. (egraether)
• Simplified easing formulas. (infusion)
• Added support to arrays in .to() using linear, catmull-rom or bezier .interpolation(). (egraether)
• Removed autostart/stop. (mrdoob)
• Renamed EaseNone, EaseIn, EaseOut ane EaseInOut, to None, In, Out and InOut. (mrdoob)
• Made .to() values dynamic. (egraether and jeromeetienne)

2011 10 15 - r5 (4,733 KB, gzip: 1,379 KB)

• Add autostart/stop functionalities (jocafa and sole)
• Add 07_autostart example demonstrating the new functionalities (sole)

2011 10 15 - r4

• Use Date.now() instead of new Date.getTime() as it's faster (mrdoob)

2011 09 30 - r3

• Added new time parameter to TWEEN.update, in order to allow synchronizing the tweens to an external timeline (lechecacharro)
• Added example to demonstrate the new synchronizing feature. (sole)

2011 06 18 - r2

• Added new utility methods getAll and removeAll for getting and removing all tweens (Paul Lewis)

2011 05 18 - r1

• Started using revision numbers in the build file
• Consider this kind of an stable revision :-)

FAQ

How do you set a tween to start after a while?

Use the delay() method: var t = new TWEEN.Tween({...}).delay(1000);

Is there a jQuery plug-in?

No, we like to keep it simple and free of dependencies. Feel free to make one yourself, though! :-)