Repository files navigation

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

More languages:English,简体中文

<divid="box"></div><style>#box {background-color: deeppink;width:100px;height:100px;}</style><scripttype="module">import{Tween,Easing}from'https://unpkg.com/@tweenjs/tween.js@23.1.3/dist/tween.esm.js'constbox=document.getElementById('box')// Get the element we want to animate.constcoords={x:0,y:0}// Start at (0, 0)consttween=newTween(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.functionanimate(time){tween.update(time)requestAnimationFrame(animate)}requestAnimationFrame(animate)</script>

Try this example on CodePen

• Does one thing only and does it well: tweens properties of an object
• Doesn't take care of CSS units (e.g. appendingpx)
• 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 intoany animation loop.

	hello world (source)		Bars (source)
	Black and red (source)		Graphs (source)
	Simplest possible example (source)		Video and time (source)
	Array interpolation (source)		Dynamic to, object (source)
	Dynamic to, interpolation array (source)		Dynamic to, large interpolation array (source)
	Repeat (source)		Relative values (source)
	Yoyo (source)		Stop all chained tweens (source)
	Custom functions (source)		Relative start time (source)
	Pause tween (source)		Complex properties (source)
	Animate an array of values (source)

The recommended method is to useimport syntax. Here we've listed variousinstall methods starting roughly with the most recommended first and leastdesirable last. Evaluate all of the following methods to pick what is mostsuitable for your project.

You can add tween.js as an npm dependency:

npm install @tweenjs/tween.js

You can import fromnode_modules if you servenode_modules as part of yourwebsite, using a standardimportmap script tag. First, assumingnode_modulesis at the root of your website, you can write an import map like so in your HTMLfile:

<scripttype="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:

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

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

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

You can also link yourimportmap to the CDN instead of a localnode_modules folder, if you prefer that:

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

If you are usingNode.js,Parcel,Webpack,Rollup,Vite, or another buildtool, then you can install@tweenjs/tween.js withnpm install @tweenjs/tween.js, andimport the library into your JavaScript (orTypeScript) file, and the build tool will know how to find the source code fromnode_modules without needing to create animportmap script:

import*asTWEENfrom'@tweenjs/tween.js'

However, note that this approach requires always running a build tool for yourapp to work, while theimportmap approach will simply work without any buildtools as a simple static HTML site.

Another approach is to download the source code with git, manually build thelibrary, then place the output in your project. Node.js is required for this.

git clone https://github.com/tweenjs/tween.jscd tween.jsnpm installnpm run build

This will create some builds in thedist directory. There are currently two different builds of the library:

• ES6 Module in/dist/tween.esm.js (recommended)
• UMD in/dist/tween.umd.js (deprecated, will be removed in a future major version)

You are now able to copy one of those two files into your project, and use like this (recommended):

<scripttype="module">import{Tween}from'path/to/tween.esm.js'</script>

or (deprecated, to be removed in future major):

<scriptsrc="path/to/tween.umd.js"></script><script>const{Tween}=TWEEN</script>

wherepath/to is replaced with the location where you placed the file.

Install a globalTWEEN variable from a content-delivery network (CDN) using the UMD file.

From cdnjs:

<scriptsrc="https://cdnjs.cloudflare.com/ajax/libs/tween.js/23.1.3/tween.umd.js"></script>

Or from unpkg.com:

<scriptsrc="https://unpkg.com/@tweenjs/tween.js@^23.1.3/dist/tween.umd.js"></script>

Then use theTWEEN variable in any script:

<script>const{Tween, Easing, Group/*, ...*/}=TWEENconsttween=newTween(someObject)// ...</script>

Skip this section if you don't know what CommonJS is!

Any of the above methods work in older systems that still use CommonJS. Repeatany of the above methods but usingdist/tween.cjs instead ofdist/tween.esm.js ordist/tween.umd.js.

• User guide
• Contributor guide
• Tutorial using tween.js with three.js
• Also:libtween, a port of tween.js to C byjsm174

You need to installnpm first--this comes with node.js, so install that one first. Then, cd totween.js's (or wherever you cloned the repo) directory and run:

npm install

To run the tests run:

npmtest

If you want to add any feature or change existing features, youmust run thetests to make sure you didn't break anything else. Any pull request (PR) needsto have updated passing tests for feature changes (or new passing tests for newfeatures or fixes) insrc/tests.ts to be accepted. Seecontributing for more information.

Maintainers:Joe Pea (@trusktr).

All contributors.