jQuery jQuery.speed() Method

What You’ll Learn

The jQuery.speed() static method builds a normalized PlainObject with duration, easing, complete, and queue for custom animations. This tutorial covers three overload signatures since jQuery 1.0 and 1.1, defaults of 400 ms and "swing", speed name normalization, plugin developer patterns, comparisons with raw .animate() options and manual defaults and jQuery.fx.off, and five hands-on examples from logging defaults to building a $.fn.pulse plugin.

Introduction

When you call .animate(), .fadeIn(), or .slideToggle(), jQuery internally normalizes the duration, easing, and callback arguments you pass. That normalization lives in jQuery.speed() — a static utility that returns a PlainObject ready for the effects engine.

Added in jQuery 1.0 (with additional overloads in 1.1), speed() is aimed at plugin developers who create new animation methods. Instead of reimplementing optional-parameter logic and default values, you call $.speed( options ) once and pass the result to .animate(). jQuery UI’s animated .addClass() follows this pattern. Defaults are duration 400 and easing "swing"; strings like "slow" map to 600 ms automatically.

Understanding the jQuery.speed() Method

Per the official jQuery API, jQuery.speed() creates an object containing properties ready for custom animation definitions. It is a static method on the global jQuery object — not something you invoke on a collection like $(selector).animate().

The returned object typically includes duration, easing, complete, and queue. jQuery fills in missing values with defaults and converts speed name strings to numeric milliseconds. Your plugin then spreads or passes those properties into .animate() without duplicating parameter hockey.

📝 Syntax

Three overload signatures on the global jQuery object:

// Overload 1 - since jQuery 1.0
jQuery.speed( duration, settings )
// Overload 2 - since jQuery 1.1
jQuery.speed( duration, easing, complete )
// Overload 3 - since jQuery 1.1
jQuery.speed( settings )

Return value and defaults

• Returns: PlainObject — normalized duration, easing, complete, queue.
• Default duration: 400 (milliseconds) when omitted.
• Default easing: "swing" when omitted.
• Speed names: "slow" → 600, "fast" → 200 (same as effect methods).

Version notes

• Added: jQuery 1.0 (duration, settings form)
• Extended: jQuery 1.1 (duration, easing, complete and settings forms)
• Status: Stable — documented for plugin developers in current jQuery releases.

Plugin developer pattern

jQuery.fn.pulse = function( options ) {
  return this.each(function() {
    var opt = jQuery.speed( options );
    jQuery( this ).animate(
      { opacity: 0.4 },
      opt.duration,
      opt.easing,
      function() {
        jQuery( this ).animate(
          { opacity: 1 },
          opt.duration,
          opt.easing,
          opt.complete
        );
      }
    );
  });
};

Examples Gallery

Each example demonstrates a core jQuery.speed() concept from default values to plugin patterns. Open DevTools or use the Try-it links. Example 1 logs the default PlainObject returned by $.speed() with no arguments.

var defaults = $.speed();
console.log( "duration:", defaults.duration );
console.log( "easing:", defaults.easing );
console.log( "complete:", defaults.complete );
console.log( "queue:", defaults.queue );
$( "#speed-output" ).html(
  "duration: " + defaults.duration +
  ", easing: " + defaults.easing
);

Console: duration: 400
easing: swing
complete: undefined (or null)
queue: true
UI: duration: 400, easing: swing

function onDone() {
  $( "#done-msg" ).text( "Animation complete!" );
}
var opt = $.speed({
  duration: 800,
  easing: "linear",
  complete: onDone
});
console.log( opt );
$( "#run-settings" ).on( "click", function() {
  $( "#settings-box" )
    .css({ left: 0 })
    .animate(
      { left: 200 },
      opt.duration,
      opt.easing,
      opt.complete
    );
} );

opt.duration: 800
opt.easing: linear
Box slides over 800 ms with linear easing
complete fires: "Animation complete!"

function onComplete() {
  $( "#three-arg-status" ).text( "Done at 600 ms" );
}
var opt = $.speed( 600, "swing", onComplete );
$( "#run-three-arg" ).on( "click", function() {
  $( "#three-arg-box" )
    .css({ opacity: 0.2 })
    .animate(
      { opacity: 1 },
      opt.duration,
      opt.easing,
      opt.complete
    );
} );

opt.duration: 600
opt.easing: swing
Fade runs 600 ms, then status: "Done at 600 ms"

$.fn.pulse = function( options ) {
  return this.each(function() {
    var opt = $.speed( options );
    var $el = $( this );
    $el.animate(
      { opacity: 0.35 },
      opt.duration,
      opt.easing,
      function() {
        $el.animate(
          { opacity: 1 },
          opt.duration,
          opt.easing,
          opt.complete
        );
      }
    );
  });
};
$( "#pulse-btn" ).on( "click", function() {
  $( ".pulse-target" ).pulse({
    duration: 400,
    easing: "swing"
  });
} );

$.fn.pulse registered
Click: targets fade to 0.35 then back to 1 over 400 ms each
opt.complete fires after second animate finishes

var slowOpt = $.speed( "slow" );
var fastOpt = $.speed( "fast" );
console.log( "slow:", slowOpt.duration );
console.log( "fast:", fastOpt.duration );
$( "#run-slow" ).on( "click", function() {
  var opt = $.speed( "slow" );
  $( "#name-box" )
    .css({ width: 40 })
    .animate({ width: 220 }, opt.duration, opt.easing );
  $( "#name-label" ).text(
    '"slow" → ' + opt.duration + " ms"
  );
} );

slow: 600
fast: 200
UI label: "slow" → 600 ms
Box width animates over 600 ms

🚀 Common Use Cases

• Custom jQuery plugins — normalize duration, easing, and callbacks in $.fn.myEffect with one $.speed( options ) call.
• jQuery UI-style extensions — mirror animated .addClass() by passing speed objects into internal .animate() chains.
• Consistent defaults — rely on 400 ms and "swing" without hardcoding fallbacks in every method.
• Speed name support — accept "slow" and "fast" in plugin APIs the same way built-in effects do.
• Debugging animation options — log $.speed( userInput ) in DevTools to see what jQuery will actually use.
• Queue control — set queue: false in the settings object when a plugin needs simultaneous tweens.

📝 Notes

• Added in jQuery 1.0 (duration, settings); extended in 1.1 with easing/complete and settings-only forms.
• Returns a PlainObject — not a jQuery collection.
• Default duration is 400 ms; default easing is "swing".
• Speed names: "slow" → 600 ms, "fast" → 200 ms.
• Intended for plugin developers creating new animation methods — built-in effects call it internally.
• The returned object may include queue — set false for concurrent animations on the same element.
• Separate from jQuery.fx.off, which globally disables tweens after options are normalized.

💡 Best Practices