.pushStack()?.pushStack(elements) (since jQuery 1.0) builds a new jQuery object from an array of DOM elements and pushes it onto the selection stack. The previous set stays available for .end().
// Official pattern
jQuery([])
.pushStack(document.getElementsByTagName("div"))
.remove()
.end();
// Plugin idea — custom set + reversible with .end()
return this.pushStack(matchedElements);
// Since 1.3 (optional metadata)
.pushStack(elements, "myMethod", [arg1, arg2]);| Need | Use |
|---|---|
Custom set that supports .end() | .pushStack(array) |
| Pop back one level | .end() |
| Merge into current set | .add() |
| Restore previous + current | .addBack() |
| Normal traversal | .find() / .filter() |
.pushStack()Start from a jQuery object, push a new element array, then chain or .end().
.pushStack(elements) on a jQuery object..end() when you want the previous set back.return this.pushStack(…) so callers can use .end().| Piece | Required? | Role |
|---|---|---|
elements | Yes | Array (or array-like) of DOM nodes |
name | No (1.3+) | Method name for serialization |
arguments | No (1.3+) | Args list for that method |
| Return value | — | New jQuery object (stacked) |
call $(currentSet).pushStack(elements)
remember currentSet as "previous"
newSet = jQuery object wrapping elements
link newSet.prevObject = previous
return newSet
later:
.end() → return previous setKeep these facts handy when writing custom chains.
| Topic | Detail |
|---|---|
| Syntax | .pushStack(elements[, name, args]) |
| Since | 1.0 (name/args since 1.3) |
| Input | Array of DOM elements |
| Stack | Pushes new set; old set kept for .end() |
| Audience | Plugins / custom traversal |
vs .add() | Replace+stack vs merge into set |
| Official demo | jQuery([]).pushStack(divs).remove().end() |
Push boxes onto the stack, mark them, then .end() and compare lengths.
Short, copy-ready snippets. Use Try It Yourself for a live editor.
pushStack + remove + endPush all .box divs, remove them, then pop the stack (CSS-free).
jQuery([])
.pushStack(document.getElementsByTagName("div"))
.filter(".box")
.remove()
.end();
$("#out").text("Boxes removed. Paragraph remains.");div nodes become the active set..box, then remove them..end() Restores the Previous LengthShow that .pushStack() is reversible with .end().
var $start = $("#list li");
var $pushed = $start.pushStack(
document.querySelectorAll("#list span")
);
$("#out").text(
"start → " + $start.length +
" | pushed → " + $pushed.length +
" | end → " + $pushed.end().length
);pushStackReturn a custom set so callers can chain and .end().
$.fn.oddItems = function () {
return this.pushStack(this.filter(":odd").get());
};
$("#list li").oddItems().append(" [odd]").end()
.append(" [all]");.get().pushStack makes that array a chained set.[odd].[all]..pushStack() vs .add()Replace+stack vs merge into the current selection.
var $li = $("#list li");
$("#out").text(
"add → " + $li.add("span").length +
" | pushStack → " + $li.pushStack(
document.querySelectorAll("#list span")
).length
);li set (combined length).pushStack stores the old li set for .end()..add(); replace for plugins with .pushStack().name and arguments (1.3+)Optional metadata for serialization — same push behavior.
var nodes = document.querySelectorAll(".box");
var $set = $([]).pushStack(nodes, "boxSet", [".box"]);
$("#out").text(
"length → " + $set.length +
" | after end → " + $set.end().length
);Check these before using .pushStack() in app code.
Prefer .find() / .filter() / .add(). Reach for .pushStack() when you write a custom method that must support .end().
.pushStack("div") is wrong. Pass an array or array-like list of nodes (e.g. from .get() or querySelectorAll).
$(array) is not the sameWrapping with $() does not stack the previous set. Without .pushStack(), .end() will not return to your prior collection.
.end() in demosIf you push and mutate, call .end() when the chain should continue on the previous set — just like the official example.
.pushStack() is a core jQuery method since 1.0 (name/arguments overload since 1.3). It works in every browser that runs your loaded jQuery version.
Universal across jQuery-supported browsers. Mainly used inside plugins that need reversible custom sets.
Bottom line: Safe and stable. Learn it for plugin authoring; prefer built-in traversal for normal pages.
| Approach | Cost | Best for |
|---|---|---|
.find() / .filter() | Cheapest habit | Everyday traversal (already stacked) |
.pushStack(smallArray) | Cheap | Plugin return values |
| Huge node lists repeatedly | Moderate | Avoid building giant arrays needlessly |
The stack link itself is cheap. Cost comes from collecting and operating on large element arrays — keep plugin results focused.
.end() to restore the previous set..add(): replace+stack vs merge into the current set.One line: .pushStack() makes a custom element array a proper jQuery chain step so .end() can undo it.
Reduce a matched set to a single element by index.
8 people found this page helpful