.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.
-
version added: 1.0.find( selector )
-
selectorType: SelectorA string containing a selector expression to match elements against.
-
-
version added: 1.6.find( element )
-
elementAn element or a jQuery object 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 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.
The expressions allowed include selectors like > p
which will find all the paragraphs that are children of the elements in the jQuery object.
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.