jQuery API

.closest()

Categories: Traversing > Tree Traversal
Contents:

.closest( selector ) Returns: jQuery

Description: Get the first element that matches the selector, beginning at the current element and progressing up through the DOM tree.

  • version added: 1.3.closest( selector )

    selectorA string containing a selector expression to match elements against.

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

    selectorA string containing a selector expression to match elements against.

    contextA 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.

Given a jQuery object that represents a set of DOM elements, the .closest() method allows us to search through these elements and their ancestors in the DOM tree and construct 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 element Begins with the parent element
Travels up the DOM tree until it finds a match for the supplied selector Travels 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 The returned jQuery object contains zero, one, or multiple elements 
  <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:

$('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:

$('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.

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.

Example:

Show how event delegation can be done with closest.

<!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).bind("click", function (e) {
      $(e.target).closest("li").toggleClass("hilight");
    });
</script>
</body>
</html>

Demo:

.closest( selectors, [ context ] ) Returns: Array

Description: Gets 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 ] )

    selectorsAn array or string containing a selector expression to match elements against (can also be a jQuery object).

    contextA 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 method is primarily meant to be used internally or by plugin authors.

Example:

Show how event delegation can be done with closest.

<!DOCTYPE html>
<html>
<head>
  <style></style>
  <script src="http://code.jquery.com/jquery-latest.js"></script>
</head>
<body>
	<ul><li></li><li></li></ul>
<script>var close = $("li:first").closest(["ul", "body"]);
        $.each(close, function(i){
  $("li").eq(i).html( this.selector + ": " + this.elem.nodeName );
});</script>
</body>
</html>

Demo:

Comments

  • Support requests, bug reports, and off-topic comments will be deleted without warning.

  • Please do post corrections or additional examples for .closest() below. We aim to quickly move corrections into the documentation.
  • If you need help, post at the forums or in the #jquery IRC channel.
  • Report bugs on the bug tracker or the jQuery Forum.
  • Discussions about the API specifically should be addressed in the Developing jQuery Core forum.
  • Worth mentioning that you can use multiple selectors ie.

    jQuery( this ).closest( 'p, tr' );

    This will return whichever element it finds first as it traverses upwards
  • PekkaS
    Yes, very useful. jQuery traversing tools are mostly targeted "inwards" and this is must have for getting parent DIV info without too much hassle. Here's getting surrounding DIV's ID when you click an item (deep) inside it:

    jQuery('#someitem').click(function(){
    parent_id = jQuery(this).closest("div[class='myparentclass']").attr("id");
    });
  • srhoades
    Best enhancement to jQuery!

    This is extremely useful as I have encountered many instances where simply finding the parent() element is insufficient.

    Previously doing a $('.obj').parent().parent().find("ul") can be replaced by a $('obj').closest('ul');

    Thank you!
  • Bob
    Can it be replaced in all instances? As the documentation shows, .closest() returns one element, while .find() returns all elements that were found. So if you wanted instead to get all the ul which are children of the obj's parents, with closest you will only get one of those children.
  • Daz
    I agree, my favourite too. This was in the last version of jQuery by the way, I bet you're kicking yourself for not knowing :)