jQuery 1.4 DOM Insertion Methods

Share this page via Facebook, Twitter or LinkedIn.

Your message has been sent.

How would you like to send this article:

Save this article to your account for easy access.

by Jonathan Chaffer Karl Swedberg | February 2010 | AJAX Open Source Web Development

All of the methods in this article by Karl Swedberg and Jonathan Chaffer, authors of jQuery 1.4 Reference Guide, manipulate the DOM in some manner. In a previous article we saw methods that simply change one of the attributes of an element, while others set an element's style properties. In this article we cover methods for DOM insertion—inside, outside, and around. These methods allow us to insert new content inside and outside an existing element, and also surrounding existing content.

DOM insertion, inside

These methods allow us to insert new content inside an existing element.

.prepend()

Insert content specified by the parameter at the beginning of each element in the set of matched elements.

.prepend(content)
.prepend(function)

Parameters (first version)

content: An element, an HTML string, or a jQuery object to insert at the beginning of each element in the set of matched elements

Parameters (second version)

function: A function that returns an HTML string to insert at the beginning of each element in the set of matched elements

Return value

The jQuery object, for chaining purposes.

Description

The .prepend() and .prependTo() methods perform the same task. The major difference is in the syntax, specifically in the placement of the content and target. With .prepend(), the selector expression preceding the method is the container into which the content is inserted. With .prependTo(), on the other hand, the content precedes the method either as a selector expression or as markup created on the fly. It is then inserted into the target container.

Consider the following HTML code:

<h2>Greetings</h2>
 <div class="container">
 <div class="inner">Hello</div>
 <div class="inner">Goodbye</div>
</div>

We can create content and insert it into several elements at once.

$('.inner').prepend('<p>Test</p>');

Each <div class="inner"> element gets the following new content:

<h2>Greetings</h2>
 <div class="container">
 <div class="inner">
 <p>Test</p>
 Hello
 </div>
 <div class="inner">
 <p>Test</p>
 Goodbye
 </div>
</div>

We can also select an element on the page and insert it into another:

$('.container').prepend($('h2'));

If an element selected this way is inserted elsewhere, it will be moved into the target (not cloned).

<div class="container">
 <h2>Greetings</h2>
 <div class="inner">Hello</div>
 <div class="inner">Goodbye</div>
</div>

However, if there are more than one target elements, cloned copies of the inserted elements will be created for each target after the first.

.prependTo()

Insert every element in the set of matched elements at the beginning of the target.

.prependTo(target)

Parameters

target: A selector, element, HTML string, or jQuery object; the matched set of elements will be inserted at the beginning of the element(s) specified by this parameter

Return value

The jQuery object, for chaining purposes.

Description

Consider the following HTML code:

<h2>Greetings</h2>
 <div class="container">
 <div class="inner">Hello</div>
 <div class="inner">Goodbye</div>
</div>

We can create content and insert it into several elements at once.

$('<p>Test</p>').prependTo('.inner');

Each inner <div> element gets the following new content:

<h2>Greetings</h2>
<div class="container">
 <div class="inner">
 <p>Test</p>
 Hello
 </div>
 <div class="inner">
 <p>Test</p>
 Goodbye
 </div>
</div>

We can also select an element on the page and insert it into another.

$('h2').prependTo($('.container'));

If an element selected this way is inserted elsewhere, it will be moved into the target (not cloned).

<div class="container">
 <h2>Greetings</h2>
 <div class="inner">Hello</div>
 <div class="inner">Goodbye</div>
</div>

However, if there are more than one target elements, cloned copies of the inserted elements will be created for each target after the first.

.append()

Insert content specified by the parameter at the end of each element in the set of matched elements.

.append(content)
.append(function)

Parameters (first version)

content: An element, an HTML string, or a jQuery object to insert at the end of each element in the set of matched elements

Parameters (second version)

function: A function that returns an HTML string to insert at the end of each element in the set of matched elements

Return value

The jQuery object, for chaining purposes.

Description

The .append() and .appendTo() methods perform the same task. The major difference is in the syntax, specifically in the placement of the content and target. With .append(), the selector expression preceding the method is the container into which the content is inserted. With .appendTo(), on the other hand, the content precedes the method either as a selector expression or as markup created on the fly, and is inserted into the target container.

Consider the following HTML code:

<h2>Greetings</h2>
<div class="container">
 <div class="inner">Hello</div>
 <div class="inner">Goodbye</div>
</div>

We can create content and insert it into several elements at once.

$('.inner').append('<p>Test</p>');

Each inner <div> element gets the following new content:

<h2>Greetings</h2>
<div class="container">
 <div class="inner">
 Hello
 <p>Test</p>
 </div>
 <div class="inner">
 Goodbye
 <p>Test</p>
 </div>
</div>

We can also select an element on the page and insert it into another.

$('.container').append($('h2'));

If an element selected this way is inserted elsewhere, it will be moved into the target (not cloned).

<div class="container">
 <div class="inner">Hello</div>
 <div class="inner">Goodbye</div>
 <h2>Greetings</h2>
</div>

However, if there is more than one target element, cloned copies of the inserted elements will be created for each target after the first.

.appendTo()

Insert every element in the set of matched elements at the end of the target.

.appendTo(target)

Parameters

target: A selector, element, HTML string, or jQuery object; the matched set of elements will be inserted at the end of the element(s) specified by this parameter

Return value

The jQuery object, for chaining purposes.

Description

Consider the following HTML code:

<h2>Greetings</h2>
<div class="container">
 <div class="inner">Hello</div>
 <div class="inner">Goodbye</div>
</div>

We can create content and insert it into several elements at once.

$('<p>Test</p>').appendTo('.inner');

Each inner <div> element gets the following new content:

<h2>Greetings</h2>
 <div class="container">
 <div class="inner">
 Hello
 <p>Test</p>
 </div>
 <div class="inner">
 Goodbye
 <p>Test</p>
 </div>
</div>

We can also select an element on the page and insert it into another.

$('h2').append($('.container'));

If an element selected this way is inserted elsewhere, it will be moved into the target (not cloned).

<div class="container">
 <div class="inner">Hello</div>
 <div class="inner">Goodbye</div>
 <h2>Greetings</h2>
</div>

However, if there are more than one target elements, cloned copies of the inserted elements will be created for each target after the first.

jQuery Reference Guide

A Comprehensive Exploration of the Popular JavaScript Library

DOM insertion, outside

These methods allow us to insert new content outside an existing element.

.before()

Insert content specified by the parameter before each element in the set of matched elements.

.before(content)
.before(function)

Parameters (first version)

content: An element, an HTML string, or a jQuery object to insert before each element in the set of matched elements

Parameters (second version)

function: A function that returns an HTML string to insert before each element in the set of matched elements

Return value

The jQuery object, for chaining purposes.

Description

The .before() and .insertBefore() methods perform the same task. The major difference is in the syntax, specifically in the placement of the content and target. With .before(), the selector expression preceding the method is the container before which the content is inserted. With .insertBefore(), on the other hand, the content precedes the method either as a selector expression or as markup created on the fly, and is inserted before the target container.

Consider the following HTML code:

<div class="container">
 <h2>Greetings</h2>
 <div class="inner">Hello</div>
 <div class="inner">Goodbye</div>
</div>

We can create content and insert it before several elements at once.

$('.inner').before('<p>Test</p>');

Each inner <div> element gets the following new content:

<div class="container">
 <h2>Greetings</h2>
 <p>Test</p>
 <div class="inner">Hello</div>
 <p>Test</p>
 <div class="inner">Goodbye</div>
</div>

We can also select an element on the page and insert it before another.

$('.container').before($('h2'));

If an element selected this way is inserted elsewhere, it will be moved before the target (not cloned).

<h2>Greetings</h2>
<div class="container">
 <div class="inner">Hello</div>
 <div class="inner">Goodbye</div>
</div>

However, if there is more than one target element, cloned copies of the inserted elements will be created for each target after the first.

.insertBefore()

Insert every element in the set of matched elements before the target.

.insertBefore(target)

Parameters

target: A selector, element, HTML string, or jQuery object; the matched set of elements will be inserted before the element(s) specified by this parameter.

Return value

The jQuery object, for chaining purposes.

Description

Consider the following HTML code:

<div class="container">
 <h2>Greetings</h2>
 <div class="inner">Hello</div>
 <div class="inner">Goodbye</div>
</div>

We can create content and insert it before several elements at once.

$('<p>Test</p>').insertBefore('.inner');

Each inner <div> element gets the following new content:

<div class="container">
 <h2>Greetings</h2>
 <p>Test</p>
 <div class="inner">Hello</div>
 <p>Test</p>
 <div class="inner">Goodbye</div>
</div>

We can also select an element on the page and insert it before another.

$('h2').insertBefore($('.container'));

If an element selected this way is inserted elsewhere, it will be moved before the target (not cloned).

<h2>Greetings</h2>
 <div class="container">
 <div class="inner">Hello</div>
 <div class="inner">Goodbye</div>
</div>

However if there are more than one target elements, cloned copies of the inserted elements will be created for each target after the first.

.after()

Insert content specified by the parameter after each element in the set of matched elements.

.after(content)
.after(function)

Parameters (first version)

content: An element, HTML string, or jQuery object to insert after each element in the set of matched elements

Parameters (second version)

function: A function that returns an HTML string to insert after each element in the set of matched elements

Return value

The jQuery object, for chaining purposes.

Description

The .after() and .insertAfter() methods perform the same task. The major difference is in the syntax, specifically in the placement of the content and target. With .after(), the selector expression preceding the method is the container after which the content is inserted. With .insertAfter(), on the other hand, the content precedes the method either as a selector expression or as markup created on the fly, and is inserted after the target container.

Consider the following HTML code:

<div class="container">
 <h2>Greetings</h2>
 <div class="inner">Hello</div>
 <div class="inner">Goodbye</div>
</div>

We can create content and insert it after several elements at once.

$('.inner').after('<p>Test</p>');

Each inner <div> element gets the following new content:

<div class="container">
 <h2>Greetings</h2>
 <div class="inner">Hello</div>
 <p>Test</p>
 <div class="inner">Goodbye</div>
 <p>Test</p>
</div>

We can also select an element on the page and insert it after another.

$('.container').after($('h2'));

If an element selected this way is inserted elsewhere, it will be moved after the target (not cloned).

<div class="container">
 <div class="inner">Hello</div>
 <div class="inner">Goodbye</div>
</div>
<h2>Greetings</h2>

However, if there are more than one target elements, cloned copies of the inserted element will be created for each target after the first.

.insertAfter()

Insert every element in the set of matched elements after the target.

.insertAfter(target)

Parameters

target: A selector, element, HTML string, or jQuery object; the matched set of elements will be inserted after the element(s) specified by this parameter

Return value

The jQuery object, for chaining purposes.

Description

Consider the following HTML code:

<div class="container">
 <h2>Greetings</h2>
 <div class="inner">Hello</div>
 <div class="inner">Goodbye</div>
</div>

We can create content and insert it after several elements at once.

$('<p>Test</p>').insertAfter('.inner');

Each inner <div> element gets the following content:

<div class="container">
 <h2>Greetings</h2>
 <div class="inner">Hello</div>
 <p>Test</p>
 <div class="inner">Goodbye</div>
 <p>Test</p>
</div>

We can also select an element on the page and insert it after another.

$('h2').insertAfter($('.container'));

If an element selected this way is inserted elsewhere, it will be moved after the target (not cloned).

<div class="container">
 <div class="inner">Hello</div>
 <div class="inner">Goodbye</div>
</div>
<h2>Greetings</h2>

However, if there are more than one target elements, cloned copies of the inserted elements will be created for each target after the first.

jQuery Reference Guide

A Comprehensive Exploration of the Popular JavaScript Library

DOM insertion, around

These methods allow us to insert new content surrounding existing content.

.wrap()

Wrap an HTML structure around each element in the set of matched elements.

.wrap(wrappingElement)
.wrap(wrappingFunction)

Parameters (first version)

wrappingElement: An HTML snippet, selector expression, jQuery object, or DOM element specifying the structure to wrap around the matched elements

Parameters (second version)

wrappingFunction: A callback function that generates a structure to wrap around the matched elements

Return value

The jQuery object, for chaining purposes.

Description

The .wrap() function can take any string or object that could be passed to the $() factory function to specify a DOM structure. This structure may be nested several levels deep, but should contain only one inmost element. The structure will be wrapped around each of the elements in the set of matched elements.

Consider the following HTML code:

<div class="container">
<div class="inner">Hello</div>
<div class="inner">Goodbye</div>
</div>

Using .wrap(), we can insert an HTML structure around the inner <div> elements as follows:

$('.inner').wrap('<div class="new" />');

The new <div> element is created on the fly and added to the DOM. The result is a new <div> wrapped around each matched element.

<div class="container">
 <div class="new">
 <div class="inner">Hello</div>
 </div>
 <div class="new">
 <div class="inner">Goodbye</div>
 </div>
</div>

The second version of this method allows us to specify a callback function instead. This callback function will be called once for every matched element. It should return a DOM element, a jQuery object, or an HTML snippet in which to wrap the corresponding element. For example:

$('.inner').wrap(function() {
 return '<div class="' + $(this).text() + '" />';
});

This will cause each <div> to have a class corresponding to the text it wraps.

<div class="container">
 <div class="Hello">
 <div class="inner">Hello</div>
 </div>
 <div class="Goodbye">
 <div class="inner">Goodbye</div>
 </div>
</div>

.wrapAll()

Wrap an HTML structure around all elements in the set of matched elements.

.wrapAll(wrappingElement)

Parameters

wrappingElement: An HTML snippet, selector expression, jQuery object, or DOM element specifying the structure to wrap around the matched elements

Return value

The jQuery object, for chaining purposes.

Description

The .wrapAll() function can take any string or object that could be passed to the $() factory function to specify a DOM structure. This structure may be nested several levels deep, but should contain only one inmost element. The structure will be wrapped around all of the elements in the set of matched elements as a single group.

Consider the following HTML code:

<div class="container">
 <div class="inner">Hello</div>
 <div class="inner">Goodbye</div>
</div>

Using .wrapAll(), we can insert an HTML structure around the inner <div> elements as follows:

$('.inner').wrapAll('<div class="new" />');

The new <div> element is created on the fly and added to the DOM. The result is a new <div> wrapped around all matched elements.

<div class="container">
 <div class="new">
 <div class="inner">Hello</div>
 <div class="inner">Goodbye</div>
 </div>
</div>

.wrapInner()

Wrap an HTML structure around the content of each element in the set of matched elements.

.wrapInner(wrappingElement)
.wrapInner(wrappingFunction)

Parameters (first version)

wrappingElement: An HTML snippet, a selector expression, a jQuery object, or a DOM element specifying the structure to wrap around the content of the matched elements

Parameters (second version)

wrappingFunction: A callback function that generates a structure to wrap around the content of the matched elements

Return value

The jQuery object, for chaining purposes.

Description

The .wrapInner() function can take any string or object that could be passed to the $() factory function to specify a DOM structure. This structure may be nested several levels deep, but should contain only one inmost element. The structure will be wrapped around the content of each of the elements in the set of matched elements.

Consider the following HTML code:

<div class="container">
 <div class="inner">Hello</div>
 <div class="inner">Goodbye</div>
</div>

Using .wrapInner(), we can insert an HTML structure around the content of the inner <div> elements as follows:

$('.inner').wrapInner('<div class="new" />');

The new <div> element is created on the fly and added to the DOM. The result is a new <div> wrapped around the content of each matched element.

<div class="container">
<div class="inner"> <div class="new">Hello</div>
</div>
<div class="inner">
<div class="new">Goodbye</div>
</div>
</div>

The second version of this method allows us to specify a callback function instead. This callback function will be called once for every matched element; it should return a DOM element, jQuery object, or HTML snippet in which to wrap the content of the corresponding element. For example:

$('.inner').wrapInner(function() {
 return '<div class="' + this.nodeValue + '" />';
});

This will cause each new <div> to have a class corresponding to the text it wraps.

<div class="container">
 <div class="inner">
 <div class="Hello">Hello</div>
 </div>
 <div class="inner">
 <div class="Goodbye">Goodbye</div>
 </div>
</div>

Summary

In this article we have covered DOM manipulation methods for Insertion inside, outside and also surrounding existing content.

If you have read this article you may be interested to view :

jQuery Reference Guide

A Comprehensive Exploration of the Popular JavaScript Library

About the Author :

Jonathan Chaffer

Jonathan Chaffer is a member of Rapid Development Group, a web development firm located in Grand Rapids, Michigan. His work there includes overseeing and implementing projects in a wide variety of technologies, with an emphasis in PHP, MySQL, and JavaScript. He also leads on-site training seminars on the jQuery framework for web developers.

In the open-source community, Jonathan has been very active in the Drupal CMS project, which has adopted jQuery as its JavaScript framework of choice. He is the creator of the Content Construction Kit, a popular module for managing structured content on Drupal sites. He is responsible for major overhauls of Drupal's menu system and developer API reference. Jonathan lives in Grand Rapids with his wife, Jennifer.

Contact Jonathan Chaffer

Karl Swedberg

Karl Swedberg is a web developer at Fusionary Media in Grand Rapids, Michigan, where he spends much of his time making cool things happen with JavaScript. As a member of the jQuery team, Karl is responsible for maintaining the jQuery API site at api.jquery.com. He also publishes tutorials on his blog, learningjquery.com, and presents at workshops and conferences. When he isn't coding, Karl likes to hang out with his family, roast coffee in his garage, and exercise at the local cross-fit gym.

Contact Karl Swedberg