.closest()

jQuery

.closest()


Contents:

.closest( selector ) Returns: jQuery

Description: For each element in the set, get the first element that matches the selector by testing the element itself and traversing up through its ancestors in the DOM tree.

  • version added: 1.3.closest( selector )

    • selector
      Type: Selector
      A string containing a selector expression to match elements against.
  • version added: 1.4.closest( selector [, context ] )

    • selector
      Type: Selector
      A string containing a selector expression to match elements against.
    • context
      Type: Element
      A DOM element within which a matching element may be found. If no context is passed in then the context of the jQuery set will be used instead.
  • version added: 1.6.closest( jQuery object )

    • jQuery object
      Type: jQuery
      A jQuery object to match elements against.
  • version added: 1.6.closest( element )

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

Given a jQuery object that represents a set of DOM elements, the .closest() method searches through these elements and their ancestors in the DOM tree and constructs a new jQuery object from the matching elements. The .parents() and .closest() methods are similar in that they both traverse up the DOM tree. The differences between the two, though subtle, are significant:

.closest() .parents()
Begins with the current elementBegins with the parent element
Travels up the DOM tree until it finds a match for the supplied selectorTravels up the DOM tree to the document's root element, adding each ancestor element to a temporary collection; it then filters that collection based on a selector if one is supplied
The returned jQuery object contains zero or one element for each element in the original setThe returned jQuery object contains zero or more elements for each element in the original set
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
                                
<ul id="one" class="level-1">
<li class="item-i">I</li>
<li id="ii" 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>

Suppose we perform a search for <ul> elements starting at item A:

1
2
                                
$('li.item-a').closest('ul')
.css('background-color', 'red');

This will change the color of the level-2 <ul>, since it is the first encountered when traveling up the DOM tree.

Suppose we search for an <li> element instead:

1
2
                                
$('li.item-a').closest('li')
.css('background-color', 'red');

This will change the color of list item A. The .closest() method begins its search with the element itself before progressing up the DOM tree, and stops when item A matches the selector.

We can pass in a DOM element as the context within which to search for the closest element.

1
2
3
4
5
                                
var listItemII = document.getElementById('ii');
$('li.item-a').closest('ul', listItemII)
.css('background-color', 'red');
$('li.item-a').closest('#one', listItemII)
.css('background-color', 'green');

This will change the color of the level-2 <ul>, because it is both the first <ul> ancestor of list item A and a descendant of list item II. It will not change the color of the level-1 <ul>, however, because it is not a descendant of list item II.

Examples:

Example: Show how event delegation can be done with closest. The closest list element toggles a yellow background when it or its descendent is clicked.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
                                  
<!DOCTYPE html>
<html>
<head>
<style>
li { margin: 3px; padding: 3px; background: #EEEEEE; }
li.hilight { background: yellow; }
</style>
<script src="http://code.jquery.com/jquery-latest.js"></script>
</head>
<body>
<ul>
<li><b>Click me!</b></li>
<li>You can also <b>Click me!</b></li>
</ul>
<script>
$( document ).on("click", function( e ) {
$( e.target ).closest("li").toggleClass("hilight");
});
</script>
</body>
</html>

Example: Pass a jQuery object to closest. The closest list element toggles a yellow background when it or its descendent is clicked.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
                                  
<!DOCTYPE html>
<html>
<head>
<style>
li { margin: 3px; padding: 3px; background: #EEEEEE; }
li.hilight { background: yellow; }
</style>
<script src="http://code.jquery.com/jquery-latest.js"></script>
</head>
<body>
<ul>
<li><b>Click me!</b></li>
<li>You can also <b>Click me!</b></li>
</ul>
<script>
var $listElements = $("li").css("color", "blue");
$( document ).on("click", function( e ) {
$( e.target ).closest( $listElements ).toggleClass("hilight");
});
</script>
</body>
</html>

.closest( selectors [, context ] ) Returns: Array version deprecated: 1.7, removed: 1.8

Description: Get an array of all the elements and selectors matched against the current element up through the DOM tree.

  • version added: 1.4.closest( selectors [, context ] )

    • selectors
      Type: Array
      An array or string containing a selector expression to match elements against (can also be a jQuery object).
    • context
      Type: Element
      A DOM element within which a matching element may be found. If no context is passed in then the context of the jQuery set will be used instead.

This signature (only!) is deprecated as of jQuery 1.7 and removed in jQuery 1.8. It was primarily meant to be used internally or by plugin authors.