What Is the jQuery wrapAll Method Used For?

The jQuery .wrapAll() method is a DOM manipulation tool used to enclose all matched elements inside a single, unified HTML container. This article explains the core purpose of .wrapAll(), how its syntax works, the critical differences between .wrapAll() and .wrap(), and how the method behaves when dealing with non-consecutive elements in the DOM tree.

Core Purpose of .wrapAll()

In web development, you frequently need to group multiple related elements into a shared container, such as placing multiple paragraphs inside a single <div> or wrapping multiple list items inside an unordered list wrapper. The .wrapAll() method selects all elements matching a specified selector and places a single HTML structure around the entire group.

Syntax

The basic syntax for .wrapAll() is:

$(selector).wrapAll(wrappingElement);

The wrappingElement argument can be:

  • An HTML string: For example, '<div class="container"></div>'.
  • A DOM element: An existing or dynamically created DOM node.
  • A jQuery object: A selected element or constructed jQuery object.
  • A selector string: A selector matching an existing element to clone as the wrapper.

Practical Example

Consider the following HTML markup:

<p class="intro">Paragraph 1</p>
<p class="intro">Paragraph 2</p>

Running this jQuery snippet:

$('.intro').wrapAll('<div class="wrapper"></div>');

Transforms the DOM into:

<div class="wrapper">
  <p class="intro">Paragraph 1</p>
  <p class="intro">Paragraph 2</p>
</div>

Both <p> elements are now nested inside the same single <div class="wrapper">.

.wrapAll() vs. .wrap()

The most common point of confusion is the distinction between .wrap() and .wrapAll():

  • .wrap(): Encloses each matched element in its own separate wrapper. Using .wrap('<div class="box"></div>') on two paragraphs produces two separate <div> containers, each holding one paragraph.
  • .wrapAll(): Encloses all matched elements together in a single shared wrapper.

Behavior with Non-Adjacent Elements

A unique characteristic of .wrapAll() occurs when the matched elements are not siblings or are separated by other elements in the DOM.

When applied to non-adjacent elements, jQuery moves all matched elements together immediately after the first matched element, and then wraps them. Consequently, this changes the layout order of your original document structure:

<p class="target">First</p>
<span>Intervening element</span>
<p class="target">Second</p>

Applying $('.target').wrapAll('<div class="group"></div>'); results in:

<div class="group">
  <p class="target">First</p>
  <p class="target">Second</p>
</div>
<span>Intervening element</span>

The second paragraph is physically relocated to be grouped with the first, leaving the intervening <span> outside the wrapper below them.