jQuery API

.add()

Categories: Traversing > Miscellaneous Traversing

.add( selector ) Returns: jQuery

Description: Add elements to the set of matched elements.

  • version added: 1.0.add( selector )

    selectorA string containing a selector expression to match additional elements against.

  • version added: 1.0.add( elements )

    elementsone or more elements to add to the set of matched elements.

  • version added: 1.0.add( html )

    htmlAn HTML fragment to add to the set of matched elements.

  • version added: 1.4.add( selector, context )

    selectorA string containing a selector expression to match additional elements against.

    contextAdd some elements rooted against the specified context.

Given a jQuery object that represents a set of DOM elements, the .add() method constructs a new jQuery object from the union of those elements and the ones passed into the method. The argument to .add() can be pretty much anything that $() accepts, including a jQuery selector expression, references to DOM elements, or an HTML snippet.

Consider a page with a simple list and a paragraph following it:

<ul>
  <li>list item 1</li>
  <li>list item 2</li>
  <li>list item 3</li>
</ul>
<p>a paragraph</p>

We can select the list items and then the paragraph by using either a selector or a reference to the DOM element itself as the .add() method's argument:

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

Or:

$('li').add(document.getElementsByTagName('p')[0])
  .css('background-color', 'red');

The result of this call is a red background behind all four elements. Using an HTML snippet as the .add() method's argument (as in the third version), we can create additional elements on the fly and add those elements to the matched set of elements. Let's say, for example, that we want to alter the background of the list items along with a newly created paragraph:

$('li').add('<p id="new">new paragraph</p>')
  .css('background-color', 'red');

Although the new paragraph has been created and its background color changed, it still does not appear on the page. To place it on the page, we could add one of the insertion methods to the chain.

As of jQuery 1.4 the results from .add() will always be returned in document order (rather than a simple concatenation).

Examples:

Example: Finds all divs and makes a border. Then adds all paragraphs to the jQuery object to set their backgrounds yellow. 

<!DOCTYPE html>
<html>
<head>
  <style>
 div { width:60px; height:60px; margin:10px; float:left; }
 p { clear:left; font-weight:bold; font-size:16px; 
     color:blue; margin:0 10px; padding:2px; }
 </style>
  <script src="http://code.jquery.com/jquery-latest.js"></script>
</head>
<body>
	<div></div>

  <div></div>
  <div></div>
  <div></div>
  <div></div>
  <div></div>

  <p>Added this... (notice no border)</p>
<script>

$("div").css("border", "2px solid red")
        .add("p")
        .css("background", "yellow");
</script>
</body>
</html>

Demo:

Example: Adds more elements, matched by the given expression, to the set of matched elements. 

<!DOCTYPE html>
<html>
<head>
  <script src="http://code.jquery.com/jquery-latest.js"></script>
</head>
<body>
	<p>Hello</p><span>Hello Again</span>
<script>$("p").add("span").css("background", "yellow");</script>
</body>
</html>

Demo:

Example: Adds more elements, created on the fly, to the set of matched elements. 

<!DOCTYPE html>
<html>
<head>
  <script src="http://code.jquery.com/jquery-latest.js"></script>
</head>
<body>
	<p>Hello</p>
<script>$("p").clone().add("<span>Again</span>").appendTo(document.body);</script>
</body>
</html>

Demo:

Example: Adds one or more Elements to the set of matched elements. 

<!DOCTYPE html>
<html>
<head>
  <script src="http://code.jquery.com/jquery-latest.js"></script>
</head>
<body>
	<p>Hello</p><span id="a">Hello Again</span>
<script>$("p").add(document.getElementById("a")).css("background", "yellow");</script>
</body>
</html>

Demo:

Example: Demonstrates how to add (or push) elements to an existing collection 

<!DOCTYPE html>
<html>
<head>
  <script src="http://code.jquery.com/jquery-latest.js"></script>
</head>
<body>
	<p>Hello</p><span id="a">Hello Again</span>
<script>var collection = $("p");
// capture the new collection
collection = collection.add(document.getElementById("a"));
collection.css("background", "yellow");</script>
</body>
</html>

Demo:

Comments

  • Support requests, bug reports, and off-topic comments will be deleted without warning.

  • Please do post corrections or additional examples for .add() below. We aim to quickly move corrections into the documentation.
  • If you need help, post at the forums or in the #jquery IRC channel.
  • Report bugs on the bug tracker or the jQuery Forum.
  • Discussions about the API specifically should be addressed in the Developing jQuery Core forum.
  • Ondrej
    I am probably doing something very wrong, but I have no success trying to do something like this:

    var foo = $("

    Hello World!

    ");
    foo.add($("

    Sweet Sweet World!

    "));
    foo.size() // returns 1 > should be 2
    foo.appendTo(document body) // render

    Hello World!



    I am using 1.4.1. Did I misunderstand how it is supposed to work?
  • judyfeng
    $("") is not selector
  • Ondrej
    Yes, it is not a selector. Is is a new DOM node, that I am trying to add to the stack. (Though the comments remove the tags - the text is supposed to be in P tag. )

    as you can do $("

    Hello

    ").appendTo(document.body)
    I am trying to append the paragraph to the stack with add() and append the whole stack later.
  • Ondrej
    again th "Hello" is supposed to be wrapped in a P tag. I have no clue. I can't seem to be able to fool the comments to display the bloody tags inline.
  • The 1.3 compat file mentions a concat method, but I don't see it in the source. Is there a concat method I can use that wouldn't order the results like add() does?
  • B@rmaley.e><e
    This method don't works with argument-function. Method insert function (!) in jQuery-chain.
    $('body').add(function(){/*function argument for add*/}) returns object:
    length: 2
    0: [object HTMLBodyElement]
    1: function(){/*function argument for add*/}
    ...