jQuery .animate() Method

What You’ll Learn

The .animate() instance method performs custom animations on numeric CSS properties. This tutorial covers both overloads since jQuery 1.0, relative += / -= values, queue: false parallel timing, the step callback, comparisons with shorthand effects and .css(), and five hands-on examples from the official jQuery API.

Introduction

jQuery ships shorthand effect methods like .fadeIn() and .slideUp() for common show/hide patterns. When you need fine-grained control over which CSS properties change and how long each transition runs, .animate() is the general-purpose tool.

Available since jQuery 1.0, .animate() accepts a plain object of CSS properties and animates each numeric value toward its target. Every call enqueues on the default fx queue unless you pass queue: false — so chained animations run one after another, just like other jQuery effects.

Understanding the .animate() Method

.animate( properties [, duration ] [, easing ] [, complete ] ) uses positional arguments for timing and a completion callback. .animate( properties, options ) passes duration, easing, queue, step, and Promise-style callbacks inside an options object.

Property values are treated as pixels unless you specify units like em, %, or in. Keywords "show", "hide", and "toggle" expand to appropriate numeric endpoints. Unlike shorthand effects, .animate() does not reveal hidden elements automatically.

📝 Syntax

Two overloads of .animate:

// 1) Positional — duration, easing, complete callback
jQuery( selector ).animate( properties [, duration ] [, easing ] [, complete ] )
// 2) Options object — queue, step, specialEasing, Promise callbacks
jQuery( selector ).animate( properties, options )

Parameters

• properties (PlainObject) — CSS properties and target values. Supports relative += / -=, and keywords "show", "hide", "toggle".
• duration (Number or String, default 400) — milliseconds, or "fast" (200) / "slow" (600).
• easing (String, default "swing") — built-in swing or linear; plugins add more.
• complete (Function) — called once per matched element when that element’s animation finishes.
• options.queue (Boolean or String, default true) — false runs immediately; string names a custom queue (requires .dequeue() to start).
• options.step (Function) — fired each frame per property; receives now and tween object fx.
• options.specialEasing (PlainObject) — per-property easing map (since 1.4).

Return value

• A jQuery object for chaining further methods on the same set.

Official jQuery API description

// Basic usage — opacity, relative left, toggle height
$( "#clickme" ).on( "click", function() {
  $( "#book" ).animate({
    opacity: 0.25,
    left: "+=50",
    height: "toggle"
  }, 5000, function() {
    // Animation complete.
  });
});

Examples Gallery

Each example demonstrates an official jQuery API .animate() pattern. Open DevTools or use the Try-it links. All five mirror the live demos on api.jquery.com/animate/.

// Using multiple unit types within one animation.
$( "#go" ).on( "click", function() {
  $( "#block" ).animate({
    width: "70%",
    opacity: 0.4,
    marginLeft: "0.6in",
    fontSize: "3em",
    borderWidth: "10px"
  }, 1500 );
});

Div expands to 70% width, fades to 40% opacity, shifts margin, grows text, thickens border — all in one 1500ms tween

$( "#right" ).on( "click", function() {
  $( ".block" ).animate({ "left": "+=50px" }, "slow" );
});
$( "#left" ).on( "click", function() {
  $( ".block" ).animate({ "left": "-=50px" }, "slow" );
});

» button: each .block moves 50px right (queued if clicked rapidly)
« button: each .block moves 50px left from its current position

$( "#go1" ).on( "click", function() {
  $( "#block1" )
    .animate({
      width: "90%"
    }, {
      queue: false,
      duration: 3000
    })
    .animate({ fontSize: "24px" }, 1500 )
    .animate({ borderRightWidth: "15px" }, 1500 );
});
$( "#go2" ).on( "click", function() {
  $( "#block2" )
    .animate({ width: "90%" }, 1000 )
    .animate({ fontSize: "24px" }, 1000 )
    .animate({ borderLeftWidth: "15px" }, 1000 );
});

Block1: width expands 3s while font and border animate in parallel afterward
Block2: width, then font, then border — each waits for the previous step

$( "#go" ).on( "click", function() {
  $( ".block" ).first().animate({
    left: 100
  }, {
    duration: 1000,
    step: function( now, fx ) {
      $( ".block" ).slice( 1 ).css( "left", now );
    }
  });
});

All blocks move left in lockstep — followers mirror the leader's left value every animation frame

$( "p" ).animate({
  height: "toggle",
  opacity: "toggle"
}, "slow" );

Visible paragraphs shrink and fade out; hidden ones expand and fade in — reversed on second run

🚀 Common Use Cases

• Custom panel motion — animate width, height, and margin together for expandable sidebars or drawers.
• Relative nudging — move elements incrementally with += / -= on arrow-key or button clicks.
• Parallel overlays — use queue: false so a background fade runs while foreground content slides.
• Synced followers — drive multiple elements from one leader via the step callback.
• Reversible toggles — collapse and expand blocks with height: "toggle" and opacity: "toggle".
• Scroll animations — tween scrollTop or custom plugin properties for smooth page navigation.

📝 Notes

• Available since jQuery 1.0; two overloads with positional args or an options object.
• Default duration is 400 ms; "fast" = 200 ms, "slow" = 600 ms.
• Unlike .fadeIn(), .animate() does not auto-show hidden elements.
• Directional properties (left, top) require non-static positioning to be visible.
• Set jQuery.fx.off = true globally to disable all animations (duration becomes 0).
• Callbacks fire once per matched element — use .promise() for a single set-level callback.

💡 Best Practices