.stop( [ clearQueue ], [ jumpToEnd ] )
Returns: jQuery
Description: Stop the currently-running animation on the matched elements.
.stop( [ clearQueue ], [ jumpToEnd ] )
version added: 1.0
clearQueue
A Boolean indicating whether to remove queued animation as well. Defaults to false.
jumpToEnd
A Boolean indicating whether to complete the current animation immediately. Defaults to false.
When .stop() is called on an element, the currently-running animation (if any) is immediately stopped. If, for instance, an element is being hidden with .slideUp() when .stop() is called, the element will now still be displayed, but will be a fraction of its previous height. Callback functions are not called.
If more than one animation method is called on the same element, the later animations are placed in the effects queue for the element. These animations will not begin until the first one completes. When .stop() is called, 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 are removed and never run.
If the jumpToEnd property is provided with a value of true, the current animation stops, but the element is immediately given its target values for each CSS property. In our above .slideUp() example, the element would be immediately hidden. The callback function is then immediately called, if provided.
The usefulness of the .stop() method is evident when we need to animate an element on mouseenter and mouseleave:
<div id="hoverme"> Hover me <img id="hoverme" src="book.png" alt="" width="100" height="123" /> </div>
We can create a nice fade effect without the common problem of multiple queued animations by adding .stop(true, true) to the chain:
Additional Notes:
- All jQuery effects, including
.stop(), can be turned off globally by settingjQuery.fx.off = true. For more information, see jQuery.fx.off.
Examples
Click the Go button once to start the animation, then click the STOP button to stop it where it's currently positioned. Another option is to click several buttons to queue them up and see that stop just kills the currently playing one.
// Start animation
$("#go").click(function(){
$(".block").animate({left: '+=100px'}, 2000);
});
// Stop animation when button is clicked
$("#stop").click(function(){
$(".block").stop();
});
// Start animation in the opposite direction
$("#back").click(function(){
$(".block").animate({left: '-=100px'}, 2000);
});
Full source:
<!DOCTYPE html> <html> <head> <script src="http://code.jquery.com/jquery-latest.js"></script> <script> $(document).ready(function(){ // Start animation $("#go").click(function(){ $(".block").animate({left: '+=100px'}, 2000); }); // Stop animation when button is clicked $("#stop").click(function(){ $(".block").stop(); }); // Start animation in the opposite direction $("#back").click(function(){ $(".block").animate({left: '-=100px'}, 2000); }); }); </script> <style>div { position: absolute; background-color: #abc; left: 0px; top:30px; width: 60px; height: 60px; margin: 5px; } </style> </head> <body> <button id="go">Go</button> <button id="stop">STOP!</button> <button id="back">Back</button> <div class="block"></div> </body> </html>
Was this information helpful?
