JSTween

Powerful JavaScript animation library for jQuery.

While good for simple effects, popular JavaScript libraries like jQuery lack the Oomph required to animate complex user interactions in the DOM. JSTween was designed from the ground up for speed and precision, allowing it to handle more simultaneous animations while maintaining a silky smooth frame rate.

Why JSTween?

Getting started with JSTween

Anatomy of a tween

$( element ).tween( { property : options } );

The tween() option parameters:

Motion tween (moves left and then alerts)

$('.target').tween({
   left:{
      start: 0,
      stop: 100,
      time: 0,
      duration: 1,
      units: 'px',
      effect: 'easeInOut',
      onStop: function(){
        alert( 'Done!' );
      }
   }
});

$.play();

There are a number of special tweens in JSTween aside from the standard CSS ones. These are here to ease cross browser compatability issues when applying CSS3, scrolling and transparency tweens.

Tip: JSTween will not set the CSS position to absolute or relative for you. You will need to do that yourself in your css before you can see things move.

Playing the timeline

Animations in JSTween are kicked off by triggering the play() method.

Playing the timeline

$.play();

You are also able to chain it if you prefer that pattern.

$('.target').tween({
   left:{
      start: 0,
      stop: 100,
      time: 0,
      duration: 1,
      units: 'px'
   }
}).play();

Interactive examples

JSTween is a powerful JavaScript animation library built from the ground up for speed and precision.

Position

$('.target').tween({
   left:{
      start: 0,
      stop: 300,
      time: 0,
      units: 'px',
      duration: 1,
      effect:'easeInOut'
   },
   top:{
      start: 0,
      stop: 200,
      time: 0,
      units: 'px',
      duration: 1,
      effect:'easeInOut'
   }
});
 
$.play();

onStart Event

$('.target').tween({
   left:{
      start: 0,
      stop: 300,
      time: 0,
      units: 'px',
      duration: 1,
      effect:'easeInOut'
   },
   top:{
      start: 0,
      stop: 200,
      time: 0,
      units: 'px',
      duration: 1,
      effect:'easeInOut',
      onStart: function( elem, state ) {
        // Do something
      }
   },
   onStart: function( elem ) {
     // Do something
   }
});
 
$.play();

onStop Event

$('.target').tween({
   left:{
      start: 0,
      stop: 300,
      time: 0,
      units: 'px',
      duration: 1,
      effect:'easeInOut'
   },
   top:{
      start: 0,
      stop: 200,
      time: 0,
      units: 'px',
      duration: 1,
      effect:'easeInOut',
      onStop: function( elem, state ) {
        // Do something
      }
   },
   onStop: function( elem ) {
     // Do something
   }
});
 
$.play();

onFrame Event

$('.target').tween({
   left:{
      start: 0,
      stop: 300,
      time: 0,
      units: 'px',
      duration: 1,
      effect:'easeInOut'
   },
   top:{
      start: 0,
      stop: 200,
      time: 0,
      units: 'px',
      duration: 1,
      effect:'easeInOut',
      onFrame: function( elem, state ) {
        // Do something
      }
   },
   onFrame: function( elem ) {
     // Do something
   }
});
 
$.play();

Background Colour

$('.target').tween({
   backgroundColor:{
      start: '#000000',
      stop: '#0000FF',
      time: 0,
      duration: 1,
      effect:'easeInOut'
   }
});
 
$.play();

Background Position

$('.target').tween({
   backgroundPosition:{
      start: '0px 0px',
      stop: '100px 100px',
      time: 0,
      duration: 1,
      effect:'easeInOut'
   }
});
 
$.play();

Dimentions

$('.target').tween({
   width:{
      start: 100,
      stop: 200,
      time: 0,
      units: 'px',
      duration: 1,
      effect:'easeInOut'
   },
   height:{
      start: 100,
      stop: 200,
      time: 0,
      units: 'px',
      duration: 1,
      effect:'easeInOut'
   }
});
 
$.play();

Borders

$('.target').tween({
   border:{
      start: 'solid 0px #000',
      stop: 'solid 15px #f00',
      time: 0,
      duration: 1,
      effect:'easeInOut'
   }
});
 
$.play();

Font Size

$('.target').tween({
   fontSize:{
      start: 0.6,
      stop: 2,
      time: 0,
      duration: 1,
      units: 'em',
      effect:'easeInOut'
   }
});
 
$.play();

z-index

$('.target').tween({
   zIndex:{
      start: 1,
      stop: 10,
      time: 1,
      duration: 1,
      units: 'em',
      effect:'easeInOut'
   }
});
 
$.play();

Opacity

$('.target').tween({
   opacity:{
      start: 100,
      stop: 50,
      time: 0,
      duration: 1,
      effect:'easeInOut'
   }
});
 
$.play();

Scrolling (Window)

//We can do this two ways
$( window ).tween({
   scroll:{
      stop: 0,
      time: 0,
      duration: 1,
      effect:'easeInOut'
   }
});
 
// Or like this..
$( window ).tween({
   scroll:{
      stop: '0px 0px',
      time: 0,
      duration: 1,
      effect:'easeInOut'
   }
});
 
$.play();

Scrolling (Element)

// Setup
$( '.target' ).css({ overflow: 'auto' });
$( '.target span' ).css({ width: 200, height: 200 })
 
//There are a few ways to do this.. 
 
// You can pass in a string..
$( '.target' ).tween({
   scroll:{
      start: '0 0',
      stop: '50 50',
      time: 0,
      duration: 1,
      effect:'easeInOut'
   }
});
 
// Or integers
$( '.target' ).tween({
   scrollTop:{
      start: 0,
      stop: 50,
      time: 0,
      duration: 1,
      effect:'easeInOut'
   }
});
 
$.play();

CSS3 Rotate

$( '.target' ).tween({
   rotate:{
      start: 0,
      stop: 360,
      time: 0,
      duration: 2,
      effect:'easeInOut'
   }
});
 
$.play();

CSS3 Transform

$( '.target' ).tween({
   transform:{
      start: 'rotate(0deg) scale( 5 )',
      stop: 'rotate(360deg) scale( 1 )',
      time: 0,
      duration: 2,
      effect:'easeInOut'
   }
});
 
$.play();

CSS3 Box Shadow

$( '.target' ).tween({
   shadow:{
      start: '0px 0px 0px #000',
      stop: '10px 10px 30px #00f',
      time: 0,
      duration: 2,
      effect:'easeInOut'
   }
});
 
$.play();

CSS3 Border Radius

$( '.target' ).tween({
   borderRadius:{
      start: 0,
      stop: 20,
      time: 0,
      duration: 2,
      units: 'px',
      effect:'easeInOut'
   },
   borderRadiusTopLeft:{
      start: 0,
      stop: 50,
      time: 0,
      duration: 2,
      units: 'px',
      effect:'easeInOut'
   }
});
 
$.play();

Setting Framerate

$.framerate( 10 );
 
$('.target').tween({
   left:{
      start: 0,
      stop: 300,
      time: 0,
      units: 'px',
      duration: 1,
      effect:'easeInOut'
   },
   top:{
      start: 0,
      stop: 200,
      time: 0,
      units: 'px',
      duration: 1,
      effect:'easeInOut'
   },
   onStop: function( elem ) {
     $.framerate( 45 ); // Set this back to normal
   }
});
 
$.play();

Clear Specific Tweens

$('.target').tween({
   left:{
      start: 0,
      stop: 300,
      time: 0,
      units: 'px',
      duration: 1,
      effect:'easeInOut'
   },
   top:{
      start: 0,
      stop: 200,
      time: 0,
      units: 'px',
      duration: 1,
      effect:'easeInOut'
   }
});
 
$('.target').clear('left'); // Clears 'left'
 
$.play();

Clear All Tweens (Does nothing)

$('.target').tween({
   left:{
      start: 0,
      stop: 300,
      time: 0,
      units: 'px',
      duration: 1,
      effect:'easeInOut'
   },
   top:{
      start: 0,
      stop: 200,
      time: 0,
      units: 'px',
      duration: 1,
      effect:'easeInOut'
   }
});
 
$('.target').clear(); // Clears all tweens
 
$.play();
JSTween

Using onStart, onFrame and onStop callbacks

JSTween allows custom functions to be triggered when a tween(s) start, stop or after each frame. This allows you to do some really powerful things. Function callbacks are passed two arguments, the current element and a "state" and an object containing the current value and units.

Tween level onStart callback (occurs before this specific tween begin)

$('.target').tween({
   left:{
      start: 0,
      stop: 100,
      time: 0,
      duration: 1,
      units: 'px',
      onStart: function( element, state ){
        // Do something funky here
      }
   }
});

$.play();

Element level onStop callback (occurs after all tweens have completed) and a tween level onFrame callback

$('.target').tween({
   left:{
      start: 0,
      stop: 100,
      time: 0,
      duration: 1,
      units: 'px',
      onFrame: function( element, state ){
        // Do something funky here
      }
   },
   onStop: function( element ){
     // Do something funky here
   }
});

$.play();

Motion effects

JSTween has the ability to apply easing effects to a tween. You can even apply effects to a colour value.

Example of a simple tween with an easing effect applied to the "left" and "color" properties

$('.target').tween({
   left:{
      start: 0,
      stop: 100,
      time: 0,
      duration: 1,
      units: 'px',
      effect: 'easeInOut'
   },
   color: {
      start: '#ffffff',
      stop: '#000000',
      time: 0,
      duration: 1,
      effect: 'bounceInOut'
   }
});

$.play();

Full list of motion effects in JSTween

Using functions() instead of predefined values

You can use functions to define any tween value in JSTween. This is really powerful enabling you to easily animate complex motions like particle effects, snow etc.. If you are animating more than one element using CSS selectors, the assigned function calls will be executed for each element passed into the tween.

Go to a random position, in a random amount of time

$('.target').tween({
   left:{
      start: 0,
      stop: function(){
        return Math.random() * 1000
      },
      time: 0,
      duration: function(){
        return Math.random() * 2
      },
      units: 'px',
      effect: 'easeInOut'
   },
   top: {
      start: 0,
      stop: function(){
        return Math.random() * 1000
      },
      time: 0,
      duration: function(){
        return Math.random() * 2
      },
      effect: 'easeInOut'
   }
});

$.play();

JSTween Helpers

JSTween exposes a number of helpers to ease cross browser CSS3 issues. Use these to apply static effects to DOM elements.

Opacity helper

// Applies a 50% transparency effect cross browser, you can also use alpha() and transparency()

$('.target').opacity(50);

Box shadow helper

$('.target').shadow('5px 5px 10px #000');

Rotate helper

$('.target').rotate(45);

Transform helper

$('.target').transform('rotate(45deg) scale(5)');

Border radius helper

$('.target').borderRadius(10, 'px');

Border radius corner helper

$('.target').borderRadiusCorner('top', 'right', 10, 'px');

Benchmarking

As we begin to increase the number of simultaneous tweens, native jQuery animation quickly begins to buckle under the weight. Notice that there is a long pause before the jQuery animation begins. This is because JSTween animations are inexpensive to create and can be batched up before you hit the play button. JSTween also uses tricks like adaptive frame rate and deferred DOM updates (a last resort) to maintain a smooth & consistent frame rate.

Animate this many elements

JSTween (Click to begin)

Native jQuery (Click to begin)