jQueryTween Features

Installation & Basic Usage

First, you need to download the package at Github and copy the distribution that suits you to your assets folders. If you are using the AIO pack (all in one), you can add the following to your site and you are ready to go.

<script type="text/javascript" src="../assets/js/jQueryTween-aio-min.js">

In other cases, you may need to have all files separate. So you need:

<script type="text/javascript" src="../assets/js/RequestAnimationFrame.js">
<script type="text/javascript" src="../assets/js/tween.min.js">		
<script type="text/javascript" src="../assets/js/jQueryTween.min.js">

The basic jQueryTween syntax:

$('.selector').jQueryTween(options,callback,special);

The extrapolated syntax:

$('.selector').jQueryTween({

  //options
    from	: {},
    to	: {}, 
    duration: 500,
    delay	: 0,
    yoyo	: false,
    easing	: TWEEN.Easing.Linear.None
  },
  
  // callback when tween is finished
  function() { 
    //some cool function
  },
  
  // special callback while tweening	
  function() {
    //another cool function
  }
);	

In the examples below we are going to explore all the options and features in detail so stay tuned.

Animating Object Size Example

//first example
$('.selector').jQueryTween({ to: { width: 150 }, yoyo: true });
//second example
$('.selector').jQueryTween({ to: { height: 150 }, yoyo: true });
//third example
$('.selector').jQueryTween({ to: { height: 150 }, yoyo: true, duration: 1500, easing: TWEEN.Easing.Cubic.Out }); 
$('.selector').jQueryTween({ to: { width: 150 }, yoyo: true, duration: 1000, delay: 500, easing: TWEEN.Easing.Bounce.In });

Tips for usage

1. Animating object dimension can be tricky, especially if the object has paddings or borders. It works best on objects with clear formatting. If your object has padding you may need to set an initial value like from: { width: $('.selector').outerHeight() } and this is to make sure the animation is not "jumpy".
2. Both width and height accept values such as 150, "150px" and "150%" but will always use the measurement unit of the target values, that's right, the { to: { width: '150px' } } values.
3. If you only do a simple width animation for instance, in most cases you don't need to specify an initial value, jQueryTween will measure it for you.
4. TIP | you can animate same object with 2 tweens at the same time, one for width and one for height, but with different options of delay, speed or easing. Just like in my demos.

Animating Color Example

//first example
$('.selector').jQueryTween({ to: { color: '#069' }, yoyo: true });
//second example
$('.selector').jQueryTween({ to: { background-color: 'rgb(0,102,153)' }, yoyo: true });

Tips for usage

1. So here we go, another thing jQuery cannot do by itself, animating color transitions.
2. Both color and background-color accept all possible cross-browser color values: #069, #006699, rgb(0,102,153) and even rgba(0,102,153,1), just that the alpha value is ignored.
3. If you only do a simple color animation for instance, in most cases you don't need to specify an initial value, jQueryTween will get it for you.
4. TIP | both color and background-color can run well in separate tween instances.

Animating Transform Translate Example

$('.selector').jQueryTween({ to: { translate: { x: 150 } }, yoyo: true });
$('.selector').jQueryTween({ to: { translate: { y: -150 } }, yoyo: true });
$('.selector').jQueryTween({ to: { translate: { z: -150 } }, yoyo: true });
$('.selector').jQueryTween({ to: { translate: { x: 150, y: -150, z: -300 } }, yoyo: true }); 

Tips for usage

1. If you only do a simple translateZ animation for instance, you will not see any effect taking place until you give the object or the object wrapper a perspective: 400px;. The more perspective value the deeper the depth of view, producing less effect.
2. Sometimes when you perform a tween with translateZ and another property, they could compete and produce little to no effect. That is because the perspective.
3. All translate properties accept values such as 150, "150px" and "150%", will always use the measurement unit of the target values, but the initial values are 0 by default and you may need to provide { from: { translate: {x: 50, y: 20} } } value if you have set the object styling this way. Why? The script cannot read the browser computed matrix3d() values, it's a matter of performance and honestly not worth the effort.
4. Notice | unlike tweening width/height, transform does not allow tweening different properties with multiple tween instances at the same time. Just like with CSS you cannot set multiple transforms at once. Only used all together in the same tween instance or CSS line. You can only combine any transform instance with any other jQueryTween supported property.

Animating Transform Rotation Example

$('.selector').jQueryTween({ to: { rotate: { x: 180 } }, yoyo: true });
$('.selector').jQueryTween({ to: { rotate: { y: -180 } }, yoyo: true });
$('.selector').jQueryTween({ to: { rotate: { x: 90, y: -180, z: -360 } }, yoyo: true }); 

Tips for usage

1. Same as for translation, rotation also requires a perspective. If the perspective is not set anywhere, the rotation would not produce a 3D effect.
2. Also same as for translate, rotation requires initial values if they were set by user via CSS, else default value 0 will be used.
3. Unlike translate, rotate always performs with degrees. So it accepts values like "180" or "180deg" only.

Animating Transform Scale Example

$('.selector').jQueryTween({ to: { scale: 2 }, yoyo: true });
$('.selector').jQueryTween({ from: {scale: 2}, to: { scale: 1 }, yoyo: true });

Tips for usage

1. scale is also a transform property, but it does not require a perspective.
2. Unlike translate or rotate, scale is always taken as absolute value. No unit required.

Animating Background Position Example

$('.selector').jQueryTween({ to: { backgroundPosition: { x: 'left' } }, yoyo: true });
$('.selector').jQueryTween({ to: { backgroundPosition: { y: '100%' } }, yoyo: true });
$('.selector').jQueryTween({ to: { backgroundPosition: { x: 90, y: 'center' } }, yoyo: true }); 

Tips for usage

1. This effect is not producing if the background image is not large enough or it's a case of background-size: cover.
2. jQueryTween only performs background position animation in percent values, but this can be easily changed if you want.
3. As you could see in the examples, it accepts strings as values but transforms them into percent. Example: "top" becomes "0%", or "center" becomes "50%".
4. Using large background images can cause severe performance drawbacks so use with caution.

Animating Object Position Example

In this example, jQueryTween is going to perform multiple tween instances for the same object with an absolute positioned element. yoyo is not used.

Let's go ahead and hit play and see what's going on.

Play

$('.selector').jQueryTween({ to: { position: { left: '50%' } } });
$('.selector').jQueryTween({ to: { position: { left: '-100%' } } });

Tips for usage

1. Notice | unlike width and height, for positioning the script does not read the current values, it will assume it's 0, so you must always define initial values in the from option. This is to avoid jumpy animations.
2. In order to perform properly, make sure the parent element is set to position: relative.
3. This effect can be used as fallback and replace translate for old browsers.
4. The positioning animation accepts for all top, right, bottom, left values such as "150", "150px" or "150%".
5. The positioning animation can work for both position: absolute and position: relative elements, except top and bottom only work for absolute.
6. To have a smooth animation and prevent jumps, you must use values for both from and to in the exact same units for initial and target values.

Animating Window Scroll Example

// a simple scroll to top
$('.selector').jQueryTween({ to: { scroll: 0 } });

//a simple way to scroll to some element
$('.selector').jQueryTween({ to: { scroll: $(this).offset().top } });

// you may want to have a smooth animation on mouse scroll, here's the code
// remember, this feature can chew your browser if has the console enabled
$(window).on('mousewheel DOMMouseScroll',function(e) {
  e.preventDefault();							
  var el = $(this);
  var scrollAmount = 250, currentScroll = $(el).scrollTop();
  var delta = e.originalEvent.wheelDelta/120 || -e.originalEvent.detail/3;
  var finalScroll = currentScroll - parseInt(delta*scrollAmount);

  $('body').jQueryTween( { to : { scroll: finalScroll }, easing: TWEEN.Easing.Exponential.Out, duration : 500 } );
});

Tips for usage

1. You don't want to use yoyo for this kind of stuff :D.
2. The selector does not really matter since we only scroll the document.body.
3. You may wanna check the ../assets/js/scripts.js I used for these demos, the scrolling can get quite fun.

Tween Manipulation Stop / Pause / Resume

$('.selector').stop(); // stops all the object's tweens
$('.selector').pause(); // pauses all the object's tweens 
$('.selector').play(); // resumes all the object's tweens

Tips for usage

1. Make sure you check the ../assets/js/scripts.js for more detailed usage.
2. The method controls all tween instances, so for instance when you pause, all tweens assigned to your object will pause.
3. Sometimes pausing delayed tweens or yoyo enabled tweens, the callback functions will trigger prematurely on resume.

Easing Functions

The tween.js distribution comes with all the easing functions that we need to perform most of the animation needs. There are 31 functions so far, here is a complete list.

The demo below will repeat 5 times, just mouse click inside the table and animations will go wild.

Callbacks

jQueryTween comes with a useful feature for callbacks. You can set a custom function after the animation is finished and even a function to execute while the tween is running. This explains what happens to the buttons on the dimension tweening example.

In the example, there are some custom functions triggered at custom events, let's explore the code a little bit.

OK. Let's take it from the start shall we? Here's the basic syntax for jQueryTween.

$('.selector').jQueryTween(options,callback,special);

Now, back to our example, looks like this.

//so when we click the button
$('.btn-width').on('click',function() {
  
  //first we cache the button object
  var bt = $(this);
  
  //next, for all buttons we change classes and disable them, we don't want to interrupt the animation
  $('.btn-width, .btn-height, .btn-width-height').removeClass('btn-jtween').addClass('btn-info disabled');

  //then we initialize our tween animation
  $('#size-example').jQueryTween({
	
	//these are the tween options
	to: { width: 150 }, duration: 1000, yoyo: true },
  
	//here we trigger the callback function when animation is finished
	function() {
	  
	  //the button gets a new text
	  $(bt).text('Play width again' );
	  
	  //all buttons are enabled and get their initial class
	  $('.btn-width, .btn-height, .btn-width-height').removeClass('btn-info disabled').addClass('btn-jtween');
	},
	
	// while animation was running, for each frame we were calling the special callback
	// this updates the button text with the current width
	function() {
	  $(bt).text('Width: ' + $('#size-example').width() + 'px' );	
	});	
});

If you only want to add a function while tween is running, you can do something like this:

$('.selector').jQueryTween( {to: { opacity: 0 } }, null, function() {
  //code for special callback goes here
  ....
}

Notice we have declared the callback on finish as null so that we can only affect what happens while tweening.

General Usage & Extend Tips

Known Issues Well not really issues, just some things to keep in mind

Wanna Contribute?