jQuery .contents() Method

What You’ll Learn

The .contents() traversing method collects all direct child nodes of each matched element — elements, text, and comments — one level down the DOM tree. This tutorial follows the official jQuery text-wrapping demos, paragraph conversion pattern, iframe document access, and compares .contents() with .children().

Introduction

A <div> might hold a paragraph element, raw text, line breaks, and even HTML comments — all as separate DOM nodes. When you call .children(), jQuery returns only the element tags and skips the text in between. To work with every direct child node, including text and comments, use .contents().

Available since jQuery 1.2, .contents() takes no arguments and travels exactly one level down — the same depth as .children() — but returns a richer set of nodes. It is especially useful for wrapping loose text, cleaning up mixed content, or reaching inside a same-origin iframe.

Understanding the .contents() Method

Given a jQuery object representing one or more DOM elements, .contents() reads the childNodes of each element and returns them as a new jQuery collection. Element nodes, text nodes, and comment nodes are all included. Since jQuery 3.2, contents of <template> elements are returned as well.

Important caveat from the jQuery docs: most jQuery methods do not support text or comment nodes — only a few (like .wrap(), .replaceWith(), and .filter()) work on them. Always filter by nodeType before chaining operations that expect elements.

📝 Syntax

General form of .contents:

.contents()

Parameters

• None — .contents() does not accept any arguments.

Return value

• A new jQuery object containing all direct child nodes (elements, text, comments) of each matched element.

Official jQuery API paragraph conversion pattern

$( ".container" )
  .contents()
  .filter( function () { return this.nodeType === 3; } )
  .wrap( "<p>" )
  .end()
  .filter( "br" )
  .remove();

Examples Gallery

Examples 1–3 follow the official jQuery API documentation. Use DevTools or the Try-it links to run each snippet in the browser.

$( "p" )
  .contents()
  .filter( function () {
    return this.nodeType !== 1;
  } )
  .wrap( "<b>" );

Text nodes inside p → wrapped in <b>
Element children (if any) → unchanged

$( ".container" )
  .contents()
  .filter( function () { return this.nodeType === 3; } )
  .wrap( "<p>" )
  .end()
  .filter( "br" )
  .remove();

Three text chunks → each wrapped in <p>
<br> separators → removed

var $box = $( "#mixed" );

console.log( "contents:", $box.contents().length ); // elements + text
console.log( "children:", $box.children().length ); // elements only

contents: 5 (text + span + text + p + text)
children: 2 (span and p only)

var labels = { 1: "element", 3: "text", 8: "comment" };

$( "#inspect" ).contents().each( function () {
  var kind = labels[ this.nodeType ] || "other";
  console.log( kind + ":", this.nodeName || this.textContent.trim().slice( 0, 20 ) );
} );

element: SPAN
text: Hello
comment: #comment
element: EM

$( "#frameDemo" ).contents().find( "a" ).css( "background-color", "#BADA55" );

All <a> elements inside same-origin iframe → #BADA55 background
Cross-origin iframe → security error, no access

🚀 Common Use Cases

• Wrap loose text — bold or paragraph-wrap text nodes that sit beside elements.
• Clean mixed markup — remove br separators after converting text blocks to paragraphs.
• Whitespace inspection — detect unexpected text nodes causing layout gaps.
• Same-origin iframe styling — theme or highlight links inside embedded documents.
• Template contents — read child nodes of <template> elements (jQuery 3.2+).
• Comment node removal — filter nodeType === 8 and strip development comments.

📝 Notes

• Available since jQuery 1.2; template element support since jQuery 3.2.
• Takes no arguments — unlike .children(selector).
• Travels exactly one DOM level — same depth as .children().
• Most jQuery methods do not work on text nodes — filter first, then chain carefully.
• Iframe access requires same-origin policy compliance.
• For element-only direct children, .children() is simpler and more predictable.

💡 Best Practices