jQuery .pushStack() Method

What You’ll Learn

.pushStack(elements) builds a new jQuery object from an array of DOM nodes and pushes it onto the internal selection stack (same API as api.jquery.com/pushStack). This tutorial covers the official demo, pairing with .end(), plugin patterns, the optional name/arguments form, five examples, and try-it labs.

Introduction

When you call .find() or .filter(), jQuery does not throw away the previous match — it keeps a stack of selections so .end() can walk back. That push behavior is exposed as .pushStack().

Since jQuery 1.0, .pushStack(elements) lets you take any array-like list of DOM nodes, wrap them as the current jQuery set, and still recover the earlier set with .end(). Plugin authors use it so custom methods feel like built-in traversal.

You rarely need .pushStack() in app UI code — prefer .find(), .filter(), and .end(). Learn it to understand the stack and to write chain-friendly plugins. See the Traversing hub.

Understanding the .pushStack() Method

Call .pushStack(elements) on a jQuery object and pass an array (or array-like collection) of DOM elements. jQuery creates a new collection from those nodes and remembers the previous collection on an internal stack.

The official demo starts from an empty set, pushes every <div> on the page, removes them, then .end() returns to the empty starter set.

📝 Syntax

Signatures:

.pushStack( elements )                      // 1.0+
.pushStack( elements, name, arguments )     // 1.3+

Parameters

• elements (Array) — DOM elements to wrap as the new jQuery object.
• name (String, optional) — name of the method that produced the array (serialization / debugging).
• arguments (Array, optional) — arguments passed to that method.

Return value

• A new jQuery object containing elements, stacked so .end() can restore the previous set.

Official demo

jQuery( [] )
  .pushStack( document.getElementsByTagName( "div" ) )
  .remove()
  .end();

Examples Gallery

Examples follow the official API and common plugin patterns. Use View Output or Try It Yourself to explore each case.

jQuery( [] )
  .pushStack( document.getElementsByTagName( "div" ) )
  .remove()
  .end();

All <div> elements removed from the document
.after .end() the chain is back on the empty starter set

$( "#host" )
  .css( "outline", "2px solid #94a3b8" )
  .pushStack( $( ".item" ).get() )
  .css( "background", "#fef08a" )
  .end()
  .append( "
Back on #host
" );

#host gets an outline
.item elements get a yellow background
append runs on #host after .end()

$.fn.oddChildren = function() {
  var matched = this.children().filter( ":odd" ).get();
  return this.pushStack( matched );
};

$( "#list" )
  .oddChildren()
  .css( "color", "crimson" )
  .end()
  .css( "border", "1px solid #cbd5e1" );

Odd-indexed children turn crimson
.after .end() the border applies to #list

// Everyday — find already stacks for .end()
$( "#box" ).find( "span" ).addClass( "x" ).end();

// Custom array — you must pushStack yourself
var nodes = document.querySelectorAll( "#box > span" );
$( "#box" ).pushStack( Array.from( nodes ) ).addClass( "y" ).end();

Both patterns support .end()
Prefer .find() when a selector is enough

$.fn.takeFirst = function( n ) {
  var els = this.get().slice( 0, n );
  return this.pushStack( els, "takeFirst", [ n ] );
};

$( "li" ).takeFirst( 2 ).addClass( "picked" ).end();

First two <li> elements get class "picked"
.end() restores the full li set

🚀 Common Use Cases

• Plugin traversal — return this.pushStack(matched) so callers can .end().
• Native DOM lists — wrap querySelectorAll / getElementsByTagName results in a stackable set.
• Algorithmic filters — push a subset computed in plain JavaScript.
• Understanding .find / .filter — see what built-ins do under the hood.
• Temporary work sets — act on a pushed group, then restore with .end().
• Not for simple UI — use .find() / .filter() when selectors suffice.

📝 Notes

• Added in jQuery 1.0; name/arguments overload since 1.3.
• Pass an array (or array-like) of DOM elements — not a selector string.
• Built-in methods like .find() already call the stack machinery for you.
• Pair with .end(); related: .addBack().
• Returning $(els) from a plugin without pushStack breaks .end() expectations.
• Primarily an internals / plugin API — intermediate topic for learners.

💡 Best Practices