.find()

.find( selector ) Returns: jQuery

Description: Get the descendants of each element in the current set of matched elements, filtered by a selector.

  • version added: 1.0.find( selector )

    selectorA string containing a selector expression to match elements against.

Given a jQuery object that represents a set of DOM elements, the .find() method allows us to search through the descendants of these elements in the DOM tree and construct a new jQuery object from the matching elements. The .find() and .children() methods are similar, except that the latter only travels a single level down the DOM tree.

The method accepts a selector expression of the same type that we can pass to the $() function. The elements will be filtered by testing whether they match this selector.

Consider a page with a basic nested list on it:

<ul class="level-1">
  <li class="item-i">I</li>
  <li class="item-ii">II
    <ul class="level-2">
      <li class="item-a">A</li>
      <li class="item-b">B
        <ul class="level-3">
          <li class="item-1">1</li>
          <li class="item-2">2</li>
          <li class="item-3">3</li>
        </ul>
      </li>
      <li class="item-c">C</li>
    </ul>
  </li>
  <li class="item-iii">III</li>
</ul>

If we begin at item II, we can find list items within it:

$('li.item-ii').find('li').css('background-color', 'red');

The result of this call is a red background on items A, B, 1, 2, 3, and C. Even though item II matches the selector expression, it is not included in the results; only descendants are considered candidates for the match.

As discussed in “The jQuery Factory Function” section above, selector context is implemented with the .find() method; therefore, $('li.item-ii').find('li') is equivalent to $('li', 'li.item-ii').

Unlike in the rest of the tree traversal methods, the selector expression is required in a call to .find(). If we need to retrieve all of the descendant elements, we can pass in the universal selector '*' to accomplish this.

Examples:

Example: Starts with all paragraphs and searches for descendant span elements, same as $("p span")

<!DOCTYPE html>
<html>
<head>
  <script src="http://code.jquery.com/jquery-latest.js"></script>
</head>
<body>
	<p><span>Hello</span>, how are you?</p>

  <p>Me? I'm <span>good</span>.</p>
<script>$("p").find("span").css('color','red');</script>
</body>
</html>

Demo:

Example: Add spans around each word then add a hover and italicize words with the letter t.

<!DOCTYPE html>
<html>
<head>
  <style>
  p { font-size:20px; width:200px; cursor:default; 
      color:blue; font-weight:bold; margin:0 10px; }
  .hilite { background:yellow; }
  </style>
  <script src="http://code.jquery.com/jquery-latest.js"></script>
</head>
<body>
	<p>
    When the day is short
    find that which matters to you
    or stop believing
  </p>
<script>
    var newText = $("p").text().split(" ").join("</span> <span>");
    newText = "<span>" + newText + "</span>";

    $("p").html(newText)
          .find('span')
            .hover(function () { $(this).addClass("hilite"); },
                   function () { $(this).removeClass("hilite"); })
          .end()
          .find(":contains('t')")
            .css({"font-style":"italic", "font-weight":"bolder"});

</script>
</body>
</html>

Demo: