jQuery .add() Method

What You’ll Learn

The .add() traversing method builds a new jQuery object from the union of your current matched elements and additional ones — selected by CSS selector, DOM reference, HTML string, or another jQuery collection. This tutorial follows the official jQuery API demos for styling combined sets, document order, and correct reassignment.

Introduction

jQuery selections often start narrow — all paragraphs, or every list item. Real pages need to target multiple unrelated groups at once: highlight every <div> and every <p>, or style list items together with a footer paragraph.

Instead of running the same .css() call twice, you combine collections with .add(). It accepts the same inputs as $() — selectors, DOM nodes, HTML fragments, and jQuery objects — and returns a fresh jQuery object you can keep chaining.

Understanding the .add() Method

Given a jQuery object representing a set of DOM elements, .add() constructs a new jQuery object from the union of those elements and whatever you pass in. Duplicates are removed automatically — each DOM node appears at most once in the result.

Since jQuery 1.4, when every element lives in the same document, the combined set is sorted in document order (the order nodes appear in the HTML tree), not necessarily the order you listed selectors. To undo a union, use .not() to subtract elements or .end() to step back in a chain.

📝 Syntax

General forms of .add:

.add( selector )
.add( elements )
.add( html )
.add( selection )
.add( selector, context )

Parameters

• selector — a string containing a selector expression to find additional elements (jQuery 1.0+).
• elements — one or more DOM elements to include (jQuery 1.0+).
• html — an HTML fragment; jQuery creates matching elements and adds them to the set (jQuery 1.0+). They exist in memory until you append them.
• selection — an existing jQuery object whose elements are merged in (jQuery 1.1+).
• selector, context — search for selector starting from context, like $(selector, context) (jQuery 1.4+).

Return value

• A new jQuery object containing the combined, de-duplicated elements — sorted in document order when possible.

Official jQuery API pattern

$( "p" ).add( "div" ).addClass( "widget" );

var pdiv = $( "p" ).add( "div" ); // save the union

Examples Gallery

Examples 1–2 match the official jQuery API documentation demos. Use DevTools or the Try-it links to run each snippet in the browser.

$( "div" ).css( "border", "2px solid red" )
  .add( "p" )
  .css( "background", "yellow" );

All div elements get a red border.
All div and p elements get a yellow background.
(Paragraph added via .add() shows yellow but no red border.)

$( "p" ).add( "span" ).css( "background", "yellow" );

Every p and span on the page gets background: yellow.

$( "li" ).add( "p" ).css( "background-color", "red" );

Three li items + one p → four red backgrounds.

$( "p" ).add( document.getElementById( "footer-note" ) )
  .css( "background", "yellow" );

All p elements plus #footer-note get yellow background.

var collection = $( "p" );

// WRONG — original collection unchanged:
// collection.add( document.getElementById( "footer-note" ) );

// RIGHT — capture the new union:
collection = collection.add( document.getElementById( "footer-note" ) );
collection.css( "background", "yellow" );

After reassignment, p elements + #footer-note are styled yellow.
Without reassignment, only the original p set would be styled.

🚀 Common Use Cases

• Batch styling — apply one .css() or .addClass() to headings and paragraphs together.
• Form fields — combine input, select, and textarea for validation plugins.
• Event binding — attach one .on("click") handler to buttons and links in different containers.
• Animation groups — fade unrelated panels as one jQuery collection.
• Plugin APIs — let callers pass extra nodes via .add(extra) before initialization.
• Testing counts — verify total selected nodes after merging sets with .length.

📝 Notes

• Available since jQuery 1.0; document-order sorting guaranteed since jQuery 1.4.
• Always capture the return value — .add() does not modify the original jQuery object in place.
• HTML passed to .add() creates elements in memory; they are not visible until you append them.
• Reverse with .not() to subtract, or .end() to revert a chain step.
• Do not confuse with .append(), which inserts content into the DOM tree.
• Elements from different documents may not have a defined sort order.

💡 Best Practices