.find()


.find( selector )Returns: jQuery

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:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
<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:

1
$( "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:

1
var allListElements = $( "li" );

And then pass this jQuery object to find:

1
$( "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:

1
2
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" )

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
<!doctype html>
<html lang="en">
<head>
<meta charset="utf-8">
<title>find 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.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
<!doctype html>
<html lang="en">
<head>
<meta charset="utf-8">
<title>find 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.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
<!doctype html>
<html lang="en">
<head>
<meta charset="utf-8">
<title>find 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: