jQuery .queue() Method

What You’ll Learn

The .queue() instance method shows, adds to, or replaces the function queue on matched elements. This tutorial covers all three overloads since jQuery 1.2, the default fx effects queue, comparisons with animate callbacks and .dequeue(), the official read/add/replace demos, and five hands-on examples.

Introduction

jQuery attaches one or more queues of functions to each element. In most apps only the default fx effects queue is used. Queues let a sequence of actions run asynchronously without blocking the rest of your script.

When you write $( "#foo" ).slideUp().fadeIn(), the element starts sliding immediately but fading waits on the fx queue until slideUp completes. .queue(), available since jQuery 1.2, lets you inspect that queue, append custom steps, or replace it entirely.

Understanding the .queue() Method

.queue( [queueName] ) returns an Array of pending functions. .queue( [queueName], callback ) adds a function and returns a jQuery object. .queue( [queueName], newQueue ) replaces the queue with an array and returns jQuery.

The optional queueName defaults to "fx". Custom callbacks added with .queue(fn) must eventually call .dequeue() or invoke the next parameter — otherwise the chain stalls.

📝 Syntax

Three overloads of .queue:

// 1) Read — returns Array of pending functions
jQuery( selector ).queue( [queueName] )
// 2) Add — append callback; returns jQuery
jQuery( selector ).queue( [queueName], callback )
// 3) Replace — swap queue contents; returns jQuery
jQuery( selector ).queue( [queueName], newQueue )

Parameters

• queueName (optional String) — name of the queue. Defaults to "fx", the standard effects queue.
• callback (Function) — function to add to the end of the queue. Receives next since jQuery 1.4 — call next() to dequeue the following item.
• newQueue (Array) — array of functions that replaces the current queue contents (e.g. [] to empty).

Return value

• Read overload: an Array of pending functions.
• Add or replace overload: a jQuery object for chaining.

Official jQuery API description

// slideUp then alert — equivalent to slideUp callback
$( "#foo" ).slideUp();
$( "#foo" ).queue(function() {
  alert( "Animation complete." );
  $( this ).dequeue();
});
// Modern pattern since jQuery 1.4
$( "#test" ).queue(function( next ) {
  // Do some stuff...
  next();
});

Examples Gallery

Each example demonstrates a .queue() overload on real animation chains. Open DevTools or use the Try-it links. Examples 1, 2, and 4 mirror official jQuery API demos.

var div = $( "div" );
function runIt() {
  div
    .show( "slow" )
    .animate({ left: "+=200" }, 2000 )
    .slideToggle( 1000 )
    .slideToggle( "fast" )
    .animate({ left: "-=200" }, 1500 )
    .hide( "slow" )
    .show( 1200 )
    .slideUp( "normal", runIt );
}
function showIt() {
  var n = div.queue( "fx" );
  $( "span" ).text( n.length );
  setTimeout( showIt, 100 );
}
runIt();
showIt();

The queue length is: 7 (varies as animations enqueue/dequeue)
Count rises when steps are added, falls as each effect completes

$( document.body ).on( "click", function() {
  $( "div" )
    .show( "slow" )
    .animate({ left: "+=200" }, 2000 )
    .queue(function() {
      $( this ).addClass( "newcolor" ).dequeue();
    })
    .animate({ left: "-=200" }, 500 )
    .queue(function() {
      $( this ).removeClass( "newcolor" ).dequeue();
    })
    .slideUp();
});

Click: div shows, moves right, turns blue, moves back, turns green, slides up
Each .queue() callback calls .dequeue() so later steps are not blocked

// Using .queue() — no callback param on slideUp
$( "#foo" ).slideUp();
$( "#foo" ).queue(function( next ) {
  alert( "Animation complete." );
  next();
});
// Equivalent direct callback:
// $( "#foo" ).slideUp(function() {
//   alert( "Animation complete." );
// });

Element slides up, then alert: "Animation complete."
Same timing as slideUp(callback) — queue runs after slideUp finishes

$( "#start" ).on( "click", function() {
  $( "div" )
    .show( "slow" )
    .animate({ left: "+=200" }, 5000 )
    .queue(function() {
      $( this ).addClass( "newcolor" ).dequeue();
    })
    .animate({ left: "-=200" }, 1500 )
    .queue(function() {
      $( this ).removeClass( "newcolor" ).dequeue();
    })
    .slideUp();
});
$( "#stop" ).on( "click", function() {
  $( "div" )
    .queue( "fx", [] )
    .stop();
});

Start: long animation chain begins
Stop: pending queue cleared, current animation halted via .stop()

var $el = $( "#worker" );
$el.queue( "tasks", function( next ) {
  console.log( "Task A" );
  next();
});
$el.queue( "tasks", function( next ) {
  console.log( "Task B" );
  next();
});
console.log( "Pending tasks:", $el.queue( "tasks" ).length );
$el.dequeue( "tasks" );

Pending tasks: 2
Task A
Task B

🚀 Common Use Cases

• Inspect animation backlog — poll .queue("fx").length while effects run to debug timing.
• Mid-chain DOM updates — toggle classes or swap text between .animate() steps via .queue(fn).
• Post-animation alerts — queue callbacks when the preceding method has no callback parameter.
• Cancel pending work — replace the queue with [] or use .clearQueue() before starting fresh.
• Named serial tasks — isolate non-fx work on queues like "tasks" or "load".
• Plugin integration — let extensions append steps to an element’s animation pipeline safely.

📝 Notes

• Available since jQuery 1.2; three overloads with different return types (Array vs jQuery).
• Default queue name is "fx" — the standard effects queue.
• .slideUp().fadeIn() runs serially because fadeIn waits on the fx queue.
• Custom .queue(fn) callbacks must call .dequeue() or next() to continue.
• Since jQuery 1.4, queued functions receive a next parameter that auto-dequeues.
• .queue("fx", []) empties pending items — pair with .stop() to halt the current effect.

💡 Best Practices