# .find()

## find ( selector ) Returns: jQuery version added: 1.0

- selector
  Type: Selector
  A string containing a selector expression to match elements against.

## find ( jQuery object ) Returns: jQuery version added: 1.6

- jQuery object
  Type: Object
  A jQuery object to match elements against.

## find ( element ) Returns: jQuery version added: 1.6

- element
  Type: Element
  An element to match elements against.

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

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 first signature for the `.find()`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.

Unlike most 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.

Selector context is implemented with the `.find()` `method;` therefore, `$( "li.item-ii" ).find( "li" )` is equivalent to `$( "li", "li.item-ii" )`.

As of jQuery 1.6, we can also filter the selection with a given jQuery collection or element. With the same nested list as above, if we start with:

    var allListElements = $( "li" );

And then pass this jQuery object to find:

    $( "li.item-ii" ).find( allListElements );

This will return a jQuery collection which contains only the list elements that are descendants of item II.

Similarly, an element may also be passed to find:

    var item1 = $( "li.item-1" )[ 0 ];
    $( "li.item-ii" ).find( item1 ).css( "background-color", "red" );

The result of this call would be a red background on item 1.

## Examples:

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

    <!doctype html>
    <html lang="en">
    <head>
      <meta charset="utf-8">
      <title>css demo</title>

      <script src="//code.jquery.com/jquery-1.10.2.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: A selection using a jQuery collection of all span tags. Only spans within p tags are changed to red while others are left blue.

    <!doctype html>
    <html lang="en">
    <head>
      <meta charset="utf-8">
      <title>css demo</title>

      <style>

      span {
        color: blue;
      }

      </style>

      <script src="//code.jquery.com/jquery-1.10.2.js"></script>
    </head>
    <body>

    <p><span>Hello</span>, how are you?</p>
    <p>Me? I'm <span>good</span>.</p>
    <div>Did you <span>eat</span> yet?</div>

    <script>

    var spans = $( "span" );
    $( "p" ).find( spans ).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 lang="en">
    <head>
      <meta charset="utf-8">
      <title>css demo</title>

      <style>

      p {
        font-size: 20px;
        width: 200px;
        color: blue;
        font-weight: bold;
        margin: 0 10px;
      }
      .hilite {
        background: yellow;
      }

      </style>

      <script src="//code.jquery.com/jquery-1.10.2.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: