jQuery API

.wrapInner()

Categories: Manipulation > DOM Insertion, Around

.wrapInner( wrappingElement ) Returns: jQuery

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

  • version added: 1.2.wrapInner( wrappingElement )

    wrappingElementAn HTML snippet, selector expression, jQuery object, or DOM element specifying the structure to wrap around the content of the matched elements.

  • version added: 1.4.wrapInner( wrappingFunction )

    wrappingFunctionA callback function which generates a structure to wrap around the content of the matched elements.

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:

<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 each inner <div> elements like so:

$('.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 instead specify a callback function. 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 <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>

Examples:

Example: Selects all paragraphs and wraps a bold tag around each of its contents. 

<!DOCTYPE html>
<html>
<head>
  <style>p { background:#bbf; }</style>
  <script src="http://code.jquery.com/jquery-latest.js"></script>
</head>
<body>
	<p>Hello</p>

  <p>cruel</p>
  <p>World</p>
<script>$("p").wrapInner("<b></b>");</script>
</body>
</html>

Demo:

Example: Wraps a newly created tree of objects around the inside of the body. 

<!DOCTYPE html>
<html>
<head>
  <style>

  div { border:2px green solid; margin:2px; padding:2px; }
  p { background:yellow; margin:2px; padding:2px; }
  </style>
  <script src="http://code.jquery.com/jquery-latest.js"></script>
</head>
<body>
	Plain old text, or is it?
<script>$("body").wrapInner("<div><div><p><em><b></b></em></p></div></div>");</script>
</body>
</html>

Demo:

Example: Selects all paragraphs and wraps a bold tag around each of its contents. 

<!DOCTYPE html>
<html>
<head>
  <style>p { background:#9f9; }</style>
  <script src="http://code.jquery.com/jquery-latest.js"></script>
</head>
<body>
	<p>Hello</p>

  <p>cruel</p>
  <p>World</p>
<script>$("p").wrapInner(document.createElement("b"));</script>
</body>
</html>

Demo:

Example: Selects all paragraphs and wraps a jQuery object around each of its contents. 

<!DOCTYPE html>
<html>
<head>
  <style>

  p { background:#9f9; }
  .red { color:red; }
  </style>
  <script src="http://code.jquery.com/jquery-latest.js"></script>
</head>
<body>
	<p>Hello</p>
  <p>cruel</p>
  <p>World</p>
<script>$("p").wrapInner($("<span class='red'></span>"));</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 .wrapInner() 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.
  • Here's an example I like - I have a table with rows of test builds and test run times (in hours) in column 4. To make it easier to compare by build, I've added a simple bar graph to each time value:

    $("#tClientTestBuilds td:nth-child(4)").wrapInner(function() {
    return "<div style='background-color:#2C3D5A;color:white;width:" +
    5 * this.nodeValue + "px'> </div>";
    });
  • sun
    A clarification on the difference to .wrap() would be great to see here; ideally, in the initial description already, possibly enhanced by a code example.