@tweenjs/tween.js

What is @tweenjs/tween.js?

@tweenjs/tween.js is a simple but powerful tweening engine for JavaScript. It allows you to create smooth animations by interpolating between values over time. This can be used for animating properties of objects, such as position, scale, rotation, and more.

What are @tweenjs/tween.js's main functionalities?

Basic Tweening

This code demonstrates basic tweening where an object's properties (x and y coordinates) are animated from one state to another over a duration of 1000 milliseconds.

const TWEEN = require('@tweenjs/tween.js');

let coords = { x: 0, y: 0 };
let tween = new TWEEN.Tween(coords)
  .to({ x: 100, y: 100 }, 1000)
  .onUpdate(() => {
    console.log(coords);
  })
  .start();

function animate(time) {
  requestAnimationFrame(animate);
  TWEEN.update(time);
}

requestAnimationFrame(animate);

Easing Functions

This code demonstrates the use of easing functions to create more natural motion. The Quadratic.Out easing function is used to slow down the animation towards the end.

const TWEEN = require('@tweenjs/tween.js');

let coords = { x: 0, y: 0 };
let tween = new TWEEN.Tween(coords)
  .to({ x: 100, y: 100 }, 1000)
  .easing(TWEEN.Easing.Quadratic.Out)
  .onUpdate(() => {
    console.log(coords);
  })
  .start();

function animate(time) {
  requestAnimationFrame(animate);
  TWEEN.update(time);
}

requestAnimationFrame(animate);

Chaining Tweens

This code demonstrates chaining tweens, where one tween starts after another finishes. The x coordinate is animated first, followed by the y coordinate.

const TWEEN = require('@tweenjs/tween.js');

let coords = { x: 0, y: 0 };
let tween1 = new TWEEN.Tween(coords)
  .to({ x: 100 }, 1000);
let tween2 = new TWEEN.Tween(coords)
  .to({ y: 100 }, 1000);

tween1.chain(tween2);
tween1.start();

function animate(time) {
  requestAnimationFrame(animate);
  TWEEN.update(time);
}

requestAnimationFrame(animate);

Other packages similar to @tweenjs/tween.js

gsap

GSAP (GreenSock Animation Platform) is a robust and high-performance JavaScript animation library. It offers more features and flexibility compared to @tweenjs/tween.js, including timeline management, advanced easing, and support for SVG animations.

animejs

Anime.js is a lightweight JavaScript animation library with a simple API. It supports various types of animations, including CSS properties, SVG, DOM attributes, and JavaScript objects. It is more feature-rich and versatile compared to @tweenjs/tween.js.

popmotion

Popmotion is a functional, flexible JavaScript animation library. It provides a range of tools for creating animations and interactions, including physics-based animations. It offers more advanced features and flexibility compared to @tweenjs/tween.js.

README

tween.js

JavaScript tweening engine for easy animations, incorporating optimised Robert Penner's equations.

var box = document.createElement('div');
box.style.setProperty('background-color', '#008800');
box.style.setProperty('width', '100px');
box.style.setProperty('height', '100px');
document.body.appendChild(box);

// Setup the animation loop.
function animate(time) {
    requestAnimationFrame(animate);
    TWEEN.update(time);
}
requestAnimationFrame(animate);

var coords = { x: 0, y: 0 }; // Start at (0, 0)
var tween = new TWEEN.Tween(coords) // Create a new tween that modifies 'coords'.
        .to({ x: 300, y: 200 }, 1000) // Move to (300, 200) in 1 second.
        .easing(TWEEN.Easing.Quadratic.Out) // Use an easing function to make the animation smooth.
        .onUpdate(function() { // Called after tween.js updates 'coords'.
            // Move 'box' to the position described by 'coords' with a CSS translation.
            box.style.setProperty('transform', 'translate(' + coords.x + 'px, ' + coords.y + 'px)');
        })
        .start(); // Start the tween immediately.

Test it with CodePen

Installation

Download the library and include it in your code:

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

You can also reference a CDN-hosted version in your code, thanks to cdnjs. For example:

<script src="https://cdnjs.cloudflare.com/ajax/libs/tween.js/16.3.5/Tween.min.js"></script>

See tween.js for more versions.

More advanced users might want to...

Use npm

npm install @tweenjs/tween.js

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

var TWEEN = require('@tweenjs/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/tweenjs --save

or install an specific tag. They are git tags, and you can run git tag in the command line for a list if you have cloned the repository locally, or you can also check out the list in the tween.js tags page. For example, to install v16.3.0:

bower install @tweenjs/tweenjs#v16.3.0

Then reference the library source:

<script src="bower_components/@tweenjs/tweenjs/src/Tween.js"></script>

Features

• Does one thing and one thing only: tween properties
• Doesn't take care of CSS units (e.g. appending px)
• Doesn't interpolate colours
• Easing functions are reusable outside of Tween
• Can also use custom easing functions

Documentation

• User guide
• Contributor guide
• Tutorial using tween.js with three.js
• Also: libtween, a port of tween.js to C by jsm174
• Also: es6-tween, a port of tween.js to ES6/Harmony by dalisoft

Examples

	Custom functions (source)		Stop all chained tweens (source)
	Yoyo (source)		Relative values (source)
	Repeat (source)		Dynamic to (source)
	Array interpolation (source)		Video and time (source)
	Simplest possible example (source)		Graphs (source)
	Black and red (source)		Bars (source)
	hello world (source)

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 install

if running the tests for the first time, to install additional dependencies for running tests, and then run

npm test

every time you want to run the tests.

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 pull request (PR) to add something new and it doesn't have tests, or the tests don't pass, the PR won't be accepted. See contributing for more information.

People

Maintainers: mikebolt, sole.

All contributors.

Projects using tween.js