# 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] More languages: [English](./README.md), [简体中文](./README_zh-CN.md) --- ```html
``` [Try this example on CodePen](https://codepen.io/trusktr/pen/KKGaBVz?editors=1000) # 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
hello world hello world
(source)
Bars Bars
(source)
Black and red Black and red
(source)
Graphs Graphs
(source)
Simplest possible example Simplest possible example
(source)
Video and time Video and time
(source)
Array interpolation Array interpolation
(source)
Dynamic to, object Dynamic to, object
(source)
Dynamic to, interpolation array Dynamic to, interpolation array
(source)
Dynamic to, large interpolation array Dynamic to, large interpolation array
(source)
Repeat Repeat
(source)
Relative values Relative values
(source)
Yoyo Yoyo
(source)
Stop all chained tweens Stop all chained tweens
(source)
Custom functions Custom functions
(source)
Relative start time Relative start time
(source)
Pause tween Pause tween
(source)
Complex properties Complex properties
(source)
Animate an array of values Animate an array of values
(source)
Curve path Curve path
(source)
Lume 3D curve Lume 3D curve
(source)
TimeScaler TimeScaler
(source)
# 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: ```bash 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: ```html ``` Now in any of your module scripts you can import Tween.js by its package name: ```html ``` #### Import from CDN Note that, without the `importmap`, you can import directly from a CDN as with the first example above, like so: ```html ``` You can also link your `importmap` to the CDN instead of a local `node_modules` folder, if you prefer that: ```html ``` ### With a build tool If you are using [Node.js](https://nodejs.org/), [Parcel](https://parceljs.org/), [Webpack](https://webpack.js.org/), [Rollup](https://rollupjs.org/), [Vite](https://vitejs.dev/), or another build tool, then you can install `@tweenjs/tween.js` with `npm install @tweenjs/tween.js`, and `import` the library into your JavaScript (or TypeScript) file, and the build tool will know how to find the source code from `node_modules` without needing to create an `importmap` script: ```javascript import {Tween} from '@tweenjs/tween.js' ``` However, note that this approach requires always running a build tool for your app to work, while the `importmap` approach will simply work without any build tools as a simple static HTML site. Update a single tween directly with `tween.update()`. When you need to manage multiple tweens together, create a group with `new Group()`. See [Controlling groups of tweens](docs/user_guide.md#controlling-groups-of-tweens). ## Manual build Another approach is to download the source code with git, manually build the library, then place the output in your project. Node.js is required for this. ```bash git clone https://github.com/tweenjs/tween.js cd tween.js npm install npm run build ``` This will create a build in the `dist` directory: - ES6 Module in `/dist/tween.esm.js` You are now able to copy this file into your project and use it like this: ```html ``` where `path/to` is replaced with the location where you placed the file. > [!Note] > You can also download these files from unpkg, for example here: > https://unpkg.com/browse/@tweenjs/tween.js@23.1.3/dist/ # Documentation - [User guide](./docs/user_guide.md) - [Contributor guide](./docs/contributor_guide.md) - [Tutorial](https://web.archive.org/web/20220601192930/http://learningthreejs.com/blog/2011/08/17/tweenjs-for-smooth-animation/) using tween.js with three.js - Also: [libtween](https://github.com/jsm174/libtween), a port of tween.js to C by [jsm174](https://github.com/jsm174) # Tests You need to install `npm` first--this comes with node.js, so install that one first. Then, cd to `tween.js`'s (or wherever you cloned the repo) directory and run: ```bash npm install ``` To run the tests run: ```bash 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. Any pull request (PR) needs to have updated passing tests for feature changes (or new passing tests for new features or fixes) in `src/tests.ts` to be accepted. See [contributing](CONTRIBUTING.md) for more information. # People Maintainers: - [Joe Pea (@trusktr)](https://github.com/trusktr) - [Dav (@dalisoft)](https://github.com/dalisoft) [All contributors](http://github.com/tweenjs/tween.js/contributors). # Projects using tween.js [Lume](https://lume.io) [![A-Frame VR](https://tweenjs.github.io/tween.js/assets/projects/10_aframe.png)](https://aframe.io) [![MOMA Inventing Abstraction 1910-1925](https://tweenjs.github.io/tween.js/assets/projects/09_moma.png)](http://www.moma.org/interactives/exhibitions/2012/inventingabstraction/) [![Web Lab](https://tweenjs.github.io/tween.js/assets/projects/08_web_lab.png)](http://www.chromeweblab.com/) [![MACCHINA I](https://tweenjs.github.io/tween.js/assets/projects/07_macchina.png)](http://5013.es/toys/macchina) [![Minesweeper 3D](https://tweenjs.github.io/tween.js/assets/projects/06_minesweeper3d.png)](http://egraether.com/mine3d/) [![ROME](https://tweenjs.github.io/tween.js/assets/projects/05_rome.png)](http://ro.me) [![WebGL Globe](https://tweenjs.github.io/tween.js/assets/projects/04_webgl_globe.png)](http://data-arts.appspot.com/globe) [![Androidify](https://tweenjs.github.io/tween.js/assets/projects/03_androidify.png)](http://www.androidify.com/) [![The Wilderness Downtown](https://tweenjs.github.io/tween.js/assets/projects/01_wilderness.png)](http://thewildernessdowntown.com/) [![Linechart](https://tweenjs.github.io/tween.js/assets/projects/00_linechart.png)](http://dejavis.org/linechart) [npm-image]: https://img.shields.io/npm/v/@tweenjs/tween.js.svg [npm-url]: https://npmjs.org/package/@tweenjs/tween.js [downloads-image]: https://img.shields.io/npm/dm/@tweenjs/tween.js.svg [downloads-url]: https://npmjs.org/package/@tweenjs/tween.js [cdnjs-image]: https://img.shields.io/cdnjs/v/tween.js.svg [cdnjs-url]: https://cdnjs.com/libraries/tween.js