.finish() JQ Home  <<  Effects  <<  .finish()

Function queues.

Description

The .finish() method is used to stop execution of the currently running animation, remove all queued animations and complete any remaining animations for the matched set.

  • When used with no arguments the .finish() 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 jumps to its end animation value.
  • Like the .stop(true, true) method, the .finish() method clears the queue and the current animation jumps to its end value.
    • Unlike the .stop(true, true) method, the .finish() method also causes the CSS property of all queued animations to jump to their end values, as well.
  • 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
.finish( [queueName] )Stop execution of the currently running animation, remove all queued animations and complete any remaining animations for the matched set, optionally using a queue name to identify the queue.

Parameters

Parameter Description Type
queueNameA string containing the name of the queue to end animations on. Defaults to 'fx', which is the standard effects queue. String

Return

A jQuery object.

.finish() Examples Effects  <<  Top

Stop execution of the currently running animation, remove all queued animations and complete any remaining animations for 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 execution of the currently running animation, remove all queued animations and complete any remaining animations for the matched set.


$(function(){
  $('#btn25').on('click', function() {
	$('#pie').slideUp(1500)
	         .slideDown(1500);
  });
  $('#btn26').on('click', function() {
    $('#pie').finish();
  });
});

a picture of Apple and Blackberry Pie     

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 execution of the currently running animation, remove all queued animations and complete any remaining animations for the matched set.


$(function(){
  $('#btn27').on('click', function() {
    $('#cheese').slideToggle(1500);
  });
  $('#btn28').on('click', function() {
    $('#cheese').finish();
  });
});

a picture of Baked Chessecake

Press the buttons below to action the above code:

         

.finish( queueName ) Example  Effects  <<  Top

Stop execution of any currently running animations, remove all queued animations and complete any remaining animations for the matched set for animations matching the queue name.

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(){
  $('#btn29').on('click', function() {
    $('#banana').queue('cake', function(next) {
   	  $(this).show()
   	         .animate({bottom:'10'})
   	         .animate({right:'80'})
   	         .animate({right:'+=240'},1500)
             .animate({bottom:'+=50'},1500)
             .slideToggle(1000)
             .slideToggle("fast")
             .animate({right:'-=240'},1000)
             .animate({bottom:'-=50'},1500);
      next();
    })
    .dequeue('cake');
    animateImg3($('#baked'));
  });
  $('#btn30').on('click', function() {
    $('#banana').finish('cake');
  });
  function animateImg3() {
	$('#baked').animate({left:'+=240'},1500)
	           .animate({top:'+=50'},1500)
	           .slideToggle(1000)
	           .slideToggle("fast")
	           .animate({left:'-=240'},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:

         

Related Tutorials

jQuery Intermediate Tutorials - Lesson 8 - Control Effects