tween.js

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

[![NPM Version][npm-image]][npm-url] [![CDNJS][cdnjs-image]][cdnjs-url] [![NPM Downloads][downloads-image]][downloads-url] [![Build and Tests][ci-image]][ci-url]

More languages: English, 简体中文

---

<div id="box"></div>

<style>
	#box {
		background-color: deeppink;
		width: 100px;
		height: 100px;
	}
</style>

<script type="module">
	import {Tween, Easing} from 'https://unpkg.com/@tweenjs/tween.js@23.1.3/dist/tween.esm.js'

	const box = document.getElementById('box') // Get the element we want to animate.

	const coords = {x: 0, y: 0} // Start at (0, 0)

	const tween = new Tween(coords, false) // Create a new tween that modifies 'coords'.
		.to({x: 300, y: 200}, 1000) // Move to (300, 200) in 1 second.
		.easing(Easing.Quadratic.InOut) // Use an easing function to make the animation smooth.
		.onUpdate(() => {
			// 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.

	// Setup the animation loop.
	function animate(time) {
		tween.update(time)
		requestAnimationFrame(animate)
	}
	requestAnimationFrame(animate)
</script>

Try this example on CodePen

Features

• Does one thing only and does it well: tweens properties of an object
• Doesn't take care of CSS units (e.g. appending px)
• Doesn't interpolate colors
• Easing functions are reusable outside of Tween
• Can also use custom easing functions
• Doesn't make its own animation loop, making it flexible for integration into any animation loop.

Examples

<table> <tr> <td> <a href="http://tweenjs.github.io/tween.js/examples/00_hello_world.html"> <img width="100" height="50" src="https://tweenjs.github.io/tween.js/assets/examples/00_hello_world.png" alt="hello world" /> </a> </td> <td> hello world<br /> (<a href="examples/00_hello_world.html">source</a>) </td> <td> <a href="http://tweenjs.github.io/tween.js/examples/01_bars.html"> <img width="100" height="50" src="https://tweenjs.github.io/tween.js/assets/examples/01_bars.png" alt="Bars" /> </a> </td> <td> Bars<br /> (<a href="examples/01_bars.html">source</a>) </td> <tr> </tr> <td> <a href="http://tweenjs.github.io/tween.js/examples/02_black_and_red.html"> <img width="100" height="50" src="https://tweenjs.github.io/tween.js/assets/examples/02_black_and_red.png" alt="Black and red" /> </a> </td> <td> Black and red<br /> (<a href="examples/02_black_and_red.html">source</a>) </td> <td> <a href="http://tweenjs.github.io/tween.js/examples/03_graphs.html"> <img width="100" height="50" src="https://tweenjs.github.io/tween.js/assets/examples/03_graphs.png" alt="Graphs" /> </a> </td> <td> Graphs<br /> (<a href="examples/03_graphs.html">source</a>) </td> </tr> <tr> <td> <a href="http://tweenjs.github.io/tween.js/examples/04_simplest.html"> <img width="100" height="50" src="https://tweenjs.github.io/tween.js/assets/examples/04_simplest.png" alt="Simplest possible example" /> </a> </td> <td> Simplest possible example<br /> (<a href="examples/04_simplest.html">source</a>) </td> <td> <a href="http://tweenjs.github.io/tween.js/examples/05_video_and_time.html"> <img width="100" height="50" src="https://tweenjs.github.io/tween.js/assets/examples/06_video_and_time.png" alt="Video and time" /> </a> </td> <td> Video and time<br /> (<a href="examples/05_video_and_time.html">source</a>) </td> </tr> <tr> <td> <a href="http://tweenjs.github.io/tween.js/examples/06_array_interpolation.html"> <img width="100" height="50" src="https://tweenjs.github.io/tween.js/assets/examples/03_graphs.png" alt="Array interpolation" /> </a> </td> <td> Array interpolation<br /> (<a href="examples/06_array_interpolation.html">source</a>) </td> <td> <a href="http://tweenjs.github.io/tween.js/examples/07_dynamic_to.html"> <img width="100" height="50" src="https://tweenjs.github.io/tween.js/assets/examples/07_dynamic_to.png" alt="Dynamic to, object" /> </a> </td> <td> Dynamic to, object<br /> (<a href="examples/07_dynamic_to.html">source</a>) </td> </tr> <tr> <td> <a href="http://tweenjs.github.io/tween.js/examples/07a_dynamic_to_two_array_values.html"> <img width="100" height="50" src="https://tweenjs.github.io/tween.js/assets/examples/07a_dynamic_to.png" alt="Dynamic to, interpolation array" /> </a> </td> <td> Dynamic to, interpolation array<br /> (<a href="examples/07a_dynamic_to_two_array_values.html">source</a>) </td> <td> <a href="http://tweenjs.github.io/tween.js/examples/07b_dynamic_to_an_array_of_values.html"> <img width="100" height="50" src="https://tweenjs.github.io/tween.js/assets/examples/07b_dynamic_to.png" alt="Dynamic to, large interpolation array" /> </a> </td> <td> Dynamic to, large interpolation array<br /> (<a href="examples/07b_dynamic_to_an_array_of_values.html">source</a>) </td> </tr> <tr> <td> <a href="http://tweenjs.github.io/tween.js/examples/08_repeat.html"> <img width="100" height="50" src="https://tweenjs.github.io/tween.js/assets/examples/08_repeat.png" alt="Repeat" /> </a> </td> <td> Repeat<br /> (<a href="examples/08_repeat.html">source</a>) </td> <td> <a href="http://tweenjs.github.io/tween.js/examples/09_relative_values.html"> <img width="100" height="50" src="https://tweenjs.github.io/tween.js/assets/examples/09_relative.png" alt="Relative values" /> </a> </td> <td> Relative values<br /> (<a href="examples/09_relative_values.html">source</a>) </td> </tr> <tr> <td> <a href="http://tweenjs.github.io/tween.js/examples/10_yoyo.html"> <img width="100" height="50" src="https://tweenjs.github.io/tween.js/assets/examples/10_yoyo.png" alt="Yoyo" /> </a> </td> <td> Yoyo<br /> (<a href="examples/10_yoyo.html">source</a>) </td> <td> <a href="http://tweenjs.github.io/tween.js/examples/11_stop_all_chained_tweens.html"> <img width="100" height="50" src="https://tweenjs.github.io/tween.js/assets/examples/11_stop_all_chained_tweens.png" alt="Stop all chained tweens" /> </a> </td> <td> Stop all chained tweens<br /> (<a href="examples/11_stop_all_chained_tweens.html">source</a>) </td> </tr> <tr> <td> <a href="http://tweenjs.github.io/tween.js/examples/12_graphs_custom_functions.html"> <img width="100" height="50" src="https://tweenjs.github.io/tween.js/assets/examples/03_graphs.png" alt="Custom functions" /> </a> </td> <td> Custom functions<br /> (<a href="examples/12_graphs_custom_functions.html">source</a>) </td> <td> <a href="http://tweenjs.github.io/tween.js/examples/13_relative_start_time.html"> <img width="100" height="50" src="https://tweenjs.github.io/tween.js/assets/examples/13_relative_start_time.png" alt="Relative start time" /> </a> </td> <td> Relative start time<br /> (<a href="examples/13_relative_start_time.html">source</a>) </td> </tr> <tr> <td> <a href="http://tweenjs.github.io/tween.js/examples/14_pause_tween.html"> <img width="100" height="50" src="https://tweenjs.github.io/tween.js/assets/examples/14_pause_tween.png" alt="Pause tween" /> </a> </td> <td> Pause tween<br /> (<a href="examples/14_pause_tween.html">source</a>) </td> <td> <a href="http://tweenjs.github.io/tween.js/examples/15_complex_properties.html"> <img width="100" height="50" src="https://tweenjs.github.io/tween.js/assets/examples/15_complex_properties.png" alt="Complex properties" /> </a> </td> <td> Complex properties<br /> (<a href="examples/15_complex_properties.html">source</a>) </td> </tr> <tr> <td> <a href="http://tweenjs.github.io/tween.js/examples/16_animate_an_array_of_values.html"> <img width="100" height="50" src="https://tweenjs.github.io/tween.js/assets/examples/16_animate_an_array_of_values.png" alt="Animate an array of values" /> </a> </td> <td> Animate an array of values<br /> (<a href="examples/16_animate_an_array_of_values.html">source</a>) </td> </tr> </table>

Installation

The recommended method is to use import syntax. Here we've listed various install methods starting roughly with the most recommended first and least desirable last. Evaluate all of the following methods to pick what is most suitable for your project.

With npm install and import from node_modules

You can add tween.js as an npm dependency:

npm install @tweenjs/tween.js

Without a build tool

Installed locally

You can import from node_modules if you serve node_modules as part of your website, using a standard importmap script tag. First, assuming node_modules is at the root of your website, you can write an import map like so in your HTML file:

<script type="importmap">
	{
		"imports": {
			"@tweenjs/tween.js": "/node_modules/@tweenjs/tween.js/dist/tween.esm.js"
		}
	}
</script>

Now in any of your module scripts you can import Tween.js by its package name:

<script type="module">
	import {Tween} from '@tweenjs/tween.js'
</script>

Import from CDN

Note that, without the importmap, you can import directly from a CDN as with the first example above, like so:

<script type="module">
	import {Tween} from 'https://unpkg.com/browse/@tweenjs/tween.js@23.1.3/dist/tween.esm.js'
</script>

You can also link your importmap to the CDN instead of a local node_modules folder, if you prefer that:

<script type="importmap">
	{
		"imports": {
			"@tweenjs/tween.js": "https://unpkg.com/