.is()

jQuery

previous page next page

.is()

Categories: Traversing > Filtering

.is( selector ) Returns: Boolean

Description: Check the current matched set of elements against a selector, element, or jQuery object and return true if at least one of these elements matches the given arguments.

  • version added: 1.0.is( selector )

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

  • version added: 1.6.is( function(index) )

    • function(index)
      Type: Function()
      A function used as a test for the set of elements. It accepts one argument, index, which is the element's index in the jQuery collection.Within the function, this refers to the current DOM element.

  • version added: 1.6.is( jQuery object )

    • jQuery object
      Type: Object
      An existing jQuery object to match the current set of elements against.

  • version added: 1.6.is( element )

    • element
      Type: Element
      An element to match the current set of elements against.

Unlike other filtering methods, .is() does not create a new jQuery object. Instead, it allows you to test the contents of a jQuery object without modification. This is often useful inside callbacks, such as event handlers.

Suppose you have a list, with two of its items containing a child element:

1
2
3
4
5
 
                                

                                  

                                    
                                      <ul>
                                    
                                  

                                

                                

                                  

                                      <li>list <strong>item 1</strong></li>
                                  

                                

                                

                                  

                                      <li><span>list item 2</span></li>
                                  

                                

                                

                                  

                                      <li>list item 3</li>
                                  

                                

                                

                                  

                                    
                                      </ul>

You can attach a click handler to the <ul> element, and then limit the code to be triggered only when a list item itself, not one of its children, is clicked:

1
2
3
4
5
6
 
                                

                                  

                                    $("ul").click(function(event) {
                                  

                                

                                

                                  

                                      var $target = $(event.target);
                                  

                                

                                

                                  

                                      if ( $target.is("li") ) {
                                  

                                

                                

                                  

                                        $target.css("background-color", "red");
                                  

                                

                                

                                  

                                      }
                                  

                                

                                

                                  

                                    });

Now, when the user clicks on the word "list" in the first item or anywhere in the third item, the clicked list item will be given a red background. However, when the user clicks on item 1 in the first item or anywhere in the second item, nothing will occur, because in those cases the target of the event would be <strong> or <span>, respectively.

Prior to jQuery 1.7, in selector strings with positional selectors such as :first, :gt(), or :even, the positional filtering is done against the jQuery object passed to .is(), not against the containing document. So for the HTML shown above, an expression such as $("li:first").is("li:last") returns true, but $("li:first-child").is("li:last-child") returns false. In addition, a bug in Sizzle prevented many positional selectors from working properly. These two factors made positional selectors almost unusable in filters.

Starting with jQuery 1.7, selector strings with positional selectors apply the selector against the document, and then determine whether the first element of the current jQuery set matches any of the resulting elements. So for the HTML shown above, an expression such as $("li:first").is("li:last") returns false. Note that since positional selectors are jQuery additions and not W3C standard, we recommend using the W3C selectors whenever feasible.

Using a Function

The second form of this method evaluates expressions related to elements based on a function rather than a selector. For each element, if the function returns true, .is() returns true as well. For example, given a somewhat more involved HTML snippet:

1
2
3
4
5
6
7
8
 
                                

                                  

                                    
                                      <ul>
                                    
                                  

                                

                                

                                  

                                      <li><strong>list</strong> item 1 - one strong tag</li>
                                  

                                

                                

                                  

                                      <li><strong>list</strong> item <strong>2</strong> -
                                  

                                

                                

                                  

                                        two <span>strong tags</span></li>
                                  

                                

                                

                                  

                                      <li>list item 3</li>
                                  

                                

                                

                                  

                                      <li>list item 4</li>
                                  

                                

                                

                                  

                                      <li>list item 5</li>
                                  

                                

                                

                                  

                                    
                                      </ul>

You can attach a click handler to every <li> that evaluates the number of <strong> elements within the clicked <li> at that time like so:

1
2
3
4
5
6
7
8
9
10
11
 
                                

                                  

                                    $("li").click(function() {
                                  

                                

                                

                                  

                                      var $li = $(this),
                                  

                                

                                

                                  

                                        isWithTwo = $li.is(function() {
                                  

                                

                                

                                  

                                          return $('strong', this).length === 2;
                                  

                                

                                

                                  

                                        });
                                  

                                

                                

                                  

                                      if ( isWithTwo ) {
                                  

                                

                                

                                  

                                        $li.css("background-color", "green");
                                  

                                

                                

                                  

                                      } else {
                                  

                                

                                

                                  

                                        $li.css("background-color", "red");
                                  

                                

                                

                                  

                                      }
                                  

                                

                                

                                  

                                    });

Examples:

Example: Shows a few ways is() can be used inside an event handler.

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
 
                                  

                                    

                                      
                                        <!DOCTYPE html>
                                      
                                    

                                  

                                  

                                    

                                      
                                        <html>
                                      
                                    

                                  

                                  

                                    

                                      
                                        <head>
                                      
                                    

                                  

                                  

                                    

                                        <style>
                                    

                                  

                                  

                                    

                                        div { width:60px; height:60px; margin:5px; float:left;
                                    

                                  

                                  

                                    

                                            border:4px outset; background:green; text-align:center;
                                    

                                  

                                  

                                    

                                            font-weight:bolder; cursor:pointer; }
                                    

                                  

                                  

                                    

                                        .blue { background:blue; }
                                    

                                  

                                  

                                    

                                        .red { background:red; }
                                    

                                  

                                  

                                    

                                        span { color:white; font-size:16px; }
                                    

                                  

                                  

                                    

                                        p { color:red; font-weight:bolder; background:yellow;
                                    

                                  

                                  

                                    

                                            margin:3px; clear:left; display:none; }
                                    

                                  

                                  

                                    

                                      
                                        </style>
                                      
                                    

                                  

                                  

                                    

                                        <script src="http://code.jquery.com/jquery-latest.js"></script>
                                    

                                  

                                  

                                    

                                      
                                        </head>
                                      
                                    

                                  

                                  

                                    

                                      
                                        <body>
                                      
                                    

                                  

                                  

                                    

                                        <div></div>
                                    

                                  

                                  

                                    

                                      
                                        <div class="blue">
                                        </div>
                                      
                                    

                                  

                                  

                                    

                                      
                                        <div>
                                        </div>
                                      
                                    

                                  

                                  

                                    

                                      
                                        <div class="red">
                                        </div>
                                      
                                    

                                  

                                  

                                    

                                       
                                    

                                  

                                  

                                    

                                      <div><br/><span>Peter</span></div>
                                    

                                  

                                  

                                    

                                      
                                        <div class="blue">
                                        </div>
                                      
                                    

                                  

                                  

                                    

                                      <p>&nbsp;</p>
                                    

                                  

                                  

                                    

                                      
                                        <script>
                                        
                                      
                                    

                                  

                                  

                                    

                                        $("div").one('click', function () {
                                    

                                  

                                  

                                    

                                          if ($(this).is(":first-child")) {
                                    

                                  

                                  

                                    

                                            $("p").text("It's the first div.");
                                    

                                  

                                  

                                    

                                          } else if ($(this).is(".blue,.red")) {
                                    

                                  

                                  

                                    

                                            $("p").text("It's a blue or red div.");
                                    

                                  

                                  

                                    

                                          } else if ($(this).is(":contains('Peter')")) {
                                    

                                  

                                  

                                    

                                            $("p").text("It's Peter!");
                                    

                                  

                                  

                                    

                                          } else {
                                    

                                  

                                  

                                    

                                            $("p").html("It's nothing <em>special</em>.");
                                    

                                  

                                  

                                    

                                          }
                                    

                                  

                                  

                                    

                                          $("p").hide().slideDown("slow");
                                    

                                  

                                  

                                    

                                          $(this).css({"border-style": "inset", cursor:"default"});
                                    

                                  

                                  

                                    

                                        });
                                    

                                  

                                  

                                    

                                      
                                        </script>
                                      
                                    

                                  

                                  

                                    

                                       
                                    

                                  

                                  

                                    

                                      
                                        </body>
                                      
                                    

                                  

                                  

                                    

                                      
                                        </html>

Example: Returns true, because the parent of the input is a form element.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
 
                                  

                                    

                                      
                                        <!DOCTYPE html>
                                      
                                    

                                  

                                  

                                    

                                      
                                        <html>
                                      
                                    

                                  

                                  

                                    

                                      
                                        <head>
                                      
                                    

                                  

                                  

                                    

                                        <style>div { color:red; }</style>
                                    

                                  

                                  

                                    

                                        <script src="http://code.jquery.com/jquery-latest.js"></script>
                                    

                                  

                                  

                                    

                                      
                                        </head>
                                      
                                    

                                  

                                  

                                    

                                      
                                        <body>
                                      
                                    

                                  

                                  

                                    

                                        <form><input type="checkbox" /></form>
                                    

                                  

                                  

                                    

                                      
                                        <div>
                                        </div>
                                      
                                    

                                  

                                  

                                    

                                      
                                        <script>
                                        
                                      
                                    

                                  

                                  

                                    

                                        var isFormParent = $("input[type='checkbox']").parent().is("form");
                                    

                                  

                                  

                                    

                                        $("div").text("isFormParent = " + isFormParent);
                                    

                                  

                                  

                                    

                                      
                                        </script>
                                      
                                    

                                  

                                  

                                    

                                       
                                    

                                  

                                  

                                    

                                      
                                        </body>
                                      
                                    

                                  

                                  

                                    

                                      
                                        </html>

Example: Returns false, because the parent of the input is a p element.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
 
                                  

                                    

                                      
                                        <!DOCTYPE html>
                                      
                                    

                                  

                                  

                                    

                                      
                                        <html>
                                      
                                    

                                  

                                  

                                    

                                      
                                        <head>
                                      
                                    

                                  

                                  

                                    

                                        <style>div { color:red; }</style>
                                    

                                  

                                  

                                    

                                        <script src="http://code.jquery.com/jquery-latest.js"></script>
                                    

                                  

                                  

                                    

                                      
                                        </head>
                                      
                                    

                                  

                                  

                                    

                                      
                                        <body>
                                      
                                    

                                  

                                  

                                    

                                        <form><p><input type="checkbox" /></p></form>
                                    

                                  

                                  

                                    

                                        <div></div>
                                    

                                  

                                  

                                    

                                      
                                        <script>
                                        
                                      
                                    

                                  

                                  

                                    

                                        var isFormParent = $("input[type='checkbox']").parent().is("form");
                                    

                                  

                                  

                                    

                                        $("div").text("isFormParent = " + isFormParent);
                                    

                                  

                                  

                                    

                                      
                                        </script>
                                      
                                    

                                  

                                  

                                    

                                       
                                    

                                  

                                  

                                    

                                      
                                        </body>
                                      
                                    

                                  

                                  

                                    

                                      
                                        </html>

Example: Checks against an existing collection of alternating list elements. Blue, alternating list elements slide up while others turn red.

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
 
                                  

                                    

                                      
                                        <!DOCTYPE html>
                                      
                                    

                                  

                                  

                                    

                                      
                                        <html>
                                      
                                    

                                  

                                  

                                    

                                      
                                        <head>
                                      
                                    

                                  

                                  

                                    

                                        <style>li { cursor:pointer; }</style>
                                    

                                  

                                  

                                    

                                        <script src="http://code.jquery.com/jquery-latest.js"></script>
                                    

                                  

                                  

                                    

                                      
                                        </head>
                                      
                                    

                                  

                                  

                                    

                                      
                                        <body>
                                      
                                    

                                  

                                  

                                    

                                       
                                    

                                  

                                  

                                    

                                      
                                        <ul id="browsers">
                                      
                                    

                                  

                                  

                                    

                                        <li>Chrome</li>
                                    

                                  

                                  

                                    

                                        <li>Safari</li>
                                    

                                  

                                  

                                    

                                        <li>Firefox</li>
                                    

                                  

                                  

                                    

                                        <li>Opera</li>
                                    

                                  

                                  

                                    

                                      
                                        </ul>
                                      
                                    

                                  

                                  

                                    

                                      
                                        <script>
                                        
                                      
                                    

                                  

                                  

                                    

                                        var $alt = $("#browsers li:nth-child(2n)").css("background", "#00FFFF");
                                    

                                  

                                  

                                    

                                        $('li').click(function() {
                                    

                                  

                                  

                                    

                                          var $li = $(this);
                                    

                                  

                                  

                                    

                                          if ( $li.is( $alt ) ) {
                                    

                                  

                                  

                                    

                                            $li.slideUp();
                                    

                                  

                                  

                                    

                                          } else {
                                    

                                  

                                  

                                    

                                            $li.css("background", "red");
                                    

                                  

                                  

                                    

                                          }
                                    

                                  

                                  

                                    

                                        });
                                    

                                  

                                  

                                    

                                      
                                        </script>
                                      
                                    

                                  

                                  

                                    

                                       
                                    

                                  

                                  

                                    

                                      
                                        </body>
                                      
                                    

                                  

                                  

                                    

                                      
                                        </html>

Example: An alternate way to achieve the above example using an element rather than a jQuery object. Checks against an existing collection of alternating list elements. Blue, alternating list elements slide up while others turn red.

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
 
                                  

                                    

                                      
                                        <!DOCTYPE html>
                                      
                                    

                                  

                                  

                                    

                                      
                                        <html>
                                      
                                    

                                  

                                  

                                    

                                      
                                        <head>
                                      
                                    

                                  

                                  

                                    

                                        <style>li { cursor:pointer; }</style>
                                    

                                  

                                  

                                    

                                        <script src="http://code.jquery.com/jquery-latest.js"></script>
                                    

                                  

                                  

                                    

                                      
                                        </head>
                                      
                                    

                                  

                                  

                                    

                                      
                                        <body>
                                      
                                    

                                  

                                  

                                    

                                       
                                    

                                  

                                  

                                    

                                      
                                        <ul id="browsers">
                                      
                                    

                                  

                                  

                                    

                                        <li>Chrome</li>
                                    

                                  

                                  

                                    

                                        <li>Safari</li>
                                    

                                  

                                  

                                    

                                        <li>Firefox</li>
                                    

                                  

                                  

                                    

                                        <li>Opera</li>
                                    

                                  

                                  

                                    

                                      
                                        </ul>
                                      
                                    

                                  

                                  

                                    

                                      
                                        <script>
                                        
                                      
                                    

                                  

                                  

                                    

                                        var $alt = $("#browsers li:nth-child(2n)").css("background", "#00FFFF");
                                    

                                  

                                  

                                    

                                        $('li').click(function() {
                                    

                                  

                                  

                                    

                                          if ( $alt.is( this ) ) {
                                    

                                  

                                  

                                    

                                            $(this).slideUp();
                                    

                                  

                                  

                                    

                                          } else {
                                    

                                  

                                  

                                    

                                            $(this).css("background", "red");
                                    

                                  

                                  

                                    

                                          }
                                    

                                  

                                  

                                    

                                        });
                                    

                                  

                                  

                                    

                                      
                                        </script>
                                      
                                    

                                  

                                  

                                    

                                       
                                    

                                  

                                  

                                    

                                      
                                        </body>
                                      
                                    

                                  

                                  

                                    

                                      
                                        </html>
 POWERED BYHERONOTE
previous page start next page