.stop()S2C Home « Effects « .stop()

Function queues.

Description

The .stop() method is used to stop execution of the currently running animation on the matched set.

  • When used with no arguments the .stop() method will stop any animation running on the default 'fx' queue immediately. So if a method such as .slideDown() is currently animating, the method will stop executing immediately and the element being animated will stay at the size it was when the .stop() method was executed. This scenario works differently for toggled animations. If a toggled animation is stopped prematurely with the .stop() method it will trigger jQuery's internal effects tracking. Prior to jQuery 1.7 calling the the .stop() method before a toggled animation was completed would cause the animation to lose track of its state when jumpToEnd was false. Any subsequent animations would start at a new "half-way" state, sometimes resulting in the element disappearing.
  • Any callback function on the element that was stopped will NOT be called unless the jumpToEnd parameter is set to true, in which case the element is immediately given its target values for each CSS property and the callback function is then called. In this scenario the clearQueue parameter must be supplied, even with its default value of false otherwise the jumpToEnd parameter will be treated as the clearQueue parameter as they are both booleans and the clearQueue parameter is expected first by jQuery.
  • When the .stop() method is called and there are more than one animation on the same element, the next animation in the queue begins immediately. If the clearQueue parameter is provided with a value of true, then the rest of the animations in the queue for that element are removed and never run.
  • The default queue is named 'fx' and has certain properties that are not shared with named queues:
    1. The 'fx' queue will automatically .dequeue() the next function on the queue and run it if the queue hasn't started.
    2. When .dequeue() is used on a function from the 'fx' queue, it will unshift() the string 'inprogress', into the [0] location of the array, thus flagging that the 'fx' queue is currently executing.
    3. Being the default, the 'fx' queue is called by .animate() and any other function that calls it by default.

Syntax

Signature Description
.stop( [queueName] [, clearQueue]
       [, jumpToEnd] )
Stop execution of the currently running animation on the matched set, optionally using a queue name to identify the queue and/or a boolean to indicate whether to remove queued animations and/or a boolean to indicate whether to complete the current animation immediately.

Parameters

Parameter Description Type
queueNameA string containing the name of the queue. Defaults to 'fx', which is the standard effects queue.String
clearQueueA boolean indicating whether to remove queued animations. Defaults to false.Boolean
jumpToEndA boolean indicating whether to complete current animation immediately. Defaults to false.Boolean

Return

A jQuery object.

.stop() ExamplesTop

Stop execution of the currently running animation on the matched set.

In the example below when the left button is pressed we start animation of the pie image with a slow sliding up and down.

If the image is animating when the right button is pressed we stop the animation. Notice how the image stops immediately and if we restart the image animation, the image does not reset to it's original size as described in the description above.


$(function(){
  $('#btn13').on('click', function() {
	$('#pie').slideUp(1500)
	         .slideDown(1500);
  });
  $('#btn14').on('click', function() {
    $('#pie').stop();
  });
});

a picture of Almond Slices     

Press the buttons below to action the above code:

         



Stop execution of the currently running animation on the matched set on a toggled animation.

In the example below when the left button is pressed we start animation of the cheesecake image with a slow sliding up and down toggle.

If the image is animating when the right button is pressed we stop the animation. Notice how the image stops immediately and if we restart the image animation it reverts to its previous state as described in the description for toggling above.


$(function(){
  $('#btn15').on('click', function() {
    $('#cheese').slideToggle(1500);
  });
  $('#btn16').on('click', function() {
    $('#cheese').stop();
  });
});

a picture of Baked Chessecake

Press the buttons below to action the above code:

         


.stop( queueName ) ExampleTop

Stop execution of the currently running animation on the matched set using a queue name to identify the queue.

In the example below when the left button is pressed we animate the left image of baked cheesecake which used the default 'fx' queue and the right image of banana cake which uses a custom queue we call 'cake'. The left image of baked cheesecake is called recursively at the end of the function containing its animation and will run ad infinitum. The right image runs through its animations and stops.

When the right button is pressed, if the image is animating at the time, we clear the animation queue for the custom 'cake' queue and stop all animation on this queue. Notice how this has no effect on the default 'fx' queue.


$(function(){
  $('#btn11').on('click', function() {
    $('#banana').queue('cake', function(next) {
   	  $(this).show()
   	         .animate({bottom:'10'})
   	         .animate({right:'80'})
   	         .animate({right:'+=410'},1500)
             .animate({bottom:'+=50'},1500)
             .slideToggle(1000)
             .slideToggle("fast")
             .animate({right:'-=410'},1000)
             .animate({bottom:'-=50'},1500);
      next();
    })
    .dequeue('cake');
    animateImg3($('#baked'));
  });
  $('#btn22').on('click', function() {
    $('#banana').stop('cake', true, true);
  });
  function animateImg3() {
	$('#baked').animate({left:'+=610'},1500)
	           .animate({top:'+=50'},1500)
	           .slideToggle(1000)
	           .slideToggle("fast")
	           .animate({left:'-=610'},1000)
	           .animate({top:'-=50'},1500, animateImg3);
  }
});

a picture of Baked Chessecake      a picture of Banana Cake     

Press the buttons below to action the above code:

         


.stop( clearQueue ) ExampleTop

Stop execution of the currently running animation on the matched set, using a boolean to remove queued animations.

In the example below when the left button is pressed we start animating the image below.

If the image is animating when the right button is pressed we clear the animation queue, which in this case is the default 'fx' effects queue.


$(function(){
  $('#btn17').on('click', function() {
    animateImg2();
    showQueueFx();
  });
  $('#btn18').on('click', function() {
    $('#korma').stop(true);
  });
  function animateImg2(anImg) {
	anImg.show();
	anImg.animate({top:'10'});
	anImg.animate({left:'10'});
	anImg.animate({left:'+=610'},1500);
	anImg.animate({top:'+=50'},1500);
	anImg.slideToggle(1000);
	anImg.slideToggle("fast");
	anImg.animate({left:'-=610'},1000);
	anImg.animate({top:'-=50'},1500);
  }
  function showQueueFx() {
    var $fxQueue = $('#korma').queue('fx');
    $('#animspan1').text( $fxQueue.length );      
    $('#animspan2').text( $fxQueue[0] );      
    setTimeout(showQueueFx, 100);
  }
});

a picture of Korma

Default queue (fx). The queue length is: . Currently animating function:

Press the buttons below to action the above code:

         


.stop( clearQueue, jumpToEnd ) ExamplesTop

Stop execution of the currently running animation on the matched set using a boolean to indicate whether to remove queued animations and a boolean to indicate whether to complete the current animation immediately.

In the example below when the left button is pressed we start animating the image below.

If the image is animating when the centre button is pressed we clear the animation queue (clearQueue parameter = true), which in this case is the default 'fx' effects queue and jump to the end of the currently animating image.

If the image is animating when the right button is pressed we keep the animation queue (clearQueue parameter = false), which in this case is the default 'fx' effects queue and jump to the end of the currently animating image.

Check the animation queue count and see how it differs when using true or false for the clearQueue parameter.


$(function(){
  $('#btn19').on('click', function() {
    animateImg2($('#baked2'));
    showQueueFx2();
  });
  $('#btn20').on('click', function() {
    $('#baked2').stop(true, true);
  });
  $('#btn21').on('click', function() {
    $('#baked2').stop(false, true);
  });
  function animateImg2(anImg) {
    anImg.show();
    anImg.animate({top:'10'});
    anImg.animate({left:'10'});
    anImg.animate({left:'+=610'},1500);
    anImg.animate({top:'+=50'},1500);
    anImg.slideToggle(1000);
    anImg.slideToggle("fast");
    anImg.animate({left:'-=610'},1000);
    anImg.animate({top:'-=50'},1500);
  }
  function showQueueFx2() {
    var $fxQueue = $('#baked2').queue('fx');
    $('#animspan3').text( $fxQueue.length );      
    $('#animspan4').text( $fxQueue[0] );      
    setTimeout(showQueueFx2, 100);
  }
});

a picture of Baked Chessecake

Default queue (fx). The queue length is: . Currently animating function:

Press the buttons below to action the above code: