jQuery 1.4 DOM Insertion Methods

jQuery Reference Guide

,
July 2007

$10.00

A Comprehensive Exploration of the Popular JavaScript Library

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

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, 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.

$('<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

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.

$('<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.

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

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.

$('<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

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.

$('<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.

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 :


Books to Consider

comments powered by Disqus