Working with jQuery query methods

Last updated 13 January 2016.

Once a jQuery selection has been obtained using the jQuery method various properties and methods allow you to query it and work with it in other ways.

The length property

This property returns the number of items in the set:


        <div>
            <div></div>
        </div>
        <script>
            var $selection = jQuery("div");
            console.log($selection.length);     // 2
        </script>

The size method

The size method returns the same number as the length property.

The get method

The get method returns a single DOM element from the set. Alternatively, array indexing with square brackets achieves the same result.

The syntax is: var element = $selection.get(n); or var element = $selection[n];, where "n" is a 0-based index. If the "n" parameter is negative, it is interpreted as the nth last index, where -1 is taken to mean the last item (negative indexes are only for the get method - it does not work with the bracketed variant). An example:


        <div id="d1"></div>
        <div id="d2"></div>
        <div id="d3"></div>
        <script>
            var $selection = jQuery("div");
            console.log($selection[0].id);          //d1
            console.log($selection.get(-2).id);     //d2
        </script>

The eq method

The eq method returns a jQuery set with one element (or no element), identified by index.

The syntax is: var element = $selection.eq(n);, where "n" is a 0-based index. If the "n" parameter is negative, it is interpreted as the nth last index, where -1 is taken to mean the last item. An example:


        <div id="d1"></div>
        <div id="d2"></div>
        <div id="d3"></div>
        <script>
            var $selection = jQuery("div");
            console.log($selection.eq(1)[0].id);          //d2
        </script>

The first method

The first method returns a jQuery set containing the first element from the base selection (or no element if the base selection is empty)

The syntax is: var element = $selection.first();. An example:


        <div id="d1"></div>
        <div id="d2"></div>
        <div id="d3"></div>
        <script>
            var $selection = jQuery("div");
            console.log($selection.first()[0].id);          //d1
        </script>

The last method

The last method returns a jQuery set containing the last element from the base selection (or no element if the base selection is empty)

The syntax is: var element = $selection.last();. An example:


        <div id="d1"></div>
        <div id="d2"></div>
        <div id="d3"></div>
        <script>
            var $selection = jQuery("div");
            console.log($selection.last()[0].id);          //d3
        </script>

The toArray method

The toArray method returns the DOM elements contained in the base selection.

The syntax is: var element = $selection.toArray();. An example:


        <div id="d1"></div>
        <div id="d2"></div>
        <div id="d3"></div>
        <script>
            var $selection = jQuery("div");
            console.log($selection.toArray()[2].id);          //d3
        </script>

The index method

The index method returns the index of a DOM element, but it works in two different ways, depending on whether you supply an argument. The method takes a DOM element as its argument. If no argument is supplied, it returns the index of the first element in the set among its siblings in the DOM. if an argument is supplied it returns the index of the element in the set. If the specified element isn't found, the return value is -1.

The syntax is: var element = $selection.index([element]);. An example:


        <div id="d1">
            <span id="s1"></span>    
            <span id="s2" class="class1"></span>    
            <span id="s3" class="class1"></span>
        </div>
        <script>
            var s2 = jQuery("#s2")[0];
            var $selection = jQuery("*.class1");        // elements s2 and s3
            console.log($selection.index(s2));          // 0, because s2 is the first element in the selection
            console.log($selection.index());            // 1, because s2 has index 1 among the children of the parent div
        </script>

The children method

The children method returns a jQuery set of the children elements of the elements in the set. Text nodes are not returned in the result set. An optional selector argument lets you do further filtering of the result set.

The syntax is: var $selection = jQuerySet.children([selector]);. In the following example, the children of two div elements are retrieved, filtered by their class name.


        <div id="outerDiv">
            <div>
                <span id="s1" class="class2"></span>        
                <span id="s2" class="class1"></span>       
                <span id="s3" class="class1"></span>
                This is some text.
            </div>
            <div>
                <span id="s4" class="class1"></span>
            </div>
        </div>
        <script>
            var divs = jQuery("#outerDiv > div");
            var $selection = divs.children(".class1");
            console.log($selection.length);          // 3
            console.log($selection[0].id);           // s2
        </script>

The contents method

Unlike the children method the contents method returns a jQuery set of the children elements of the elements in the set, including text nodes. On the other hand, there is no optional selector parameter.

The syntax is: var $selection = jQuerySet.contents();. In the following example, the children of two div elements are retrieved and logged to the console.


        <div>
            Some text
            <span id="s4" class="class1">Span text</span>
            Some more text
        </div>
        <div>Yet more text</div>
        <script>
            var divs = jQuery("div");
            var $selection = divs.contents();
            for (var i = 0; i < $selection.length; i++)
                console.log($selection[i]);
        </script>

The output to the console is:


        <TextNode textContent="\n        Some text\n        ">
        <span id="s4" class="class1">
        <TextNode textContent="\n        Some more text\n    ">
        <TextNode textContent="Yet more text">

The find method

Unlike the children method the find method returns a jQuery set of the descendant elements of the elements in the set. Moreover, the optional selector parameter accepts a jQuery set or a plain element array in addition to a query string. In the former use case, the find method effectively constructs the intersection of the set of descendants and the elements in the collection supplied as argument. This is exemplified in the below example.

The syntax is: var $selection = jQuerySet.find([selector]);. The selector argument can be of any type you can pass to the jQuery constructor.


        <span id="s0"></span>
        <div>
            <span id="s1"></span>
        </div>
        <div>
            <span id="s2"></span>
        </div>
        <script>
            var spans = jQuery("#s0, #s1");             // 2 span elements
            var divs = jQuery("div");                   // 2 div elements
            var $selection = divs.find(spans);
            for (var i = 0; i < $selection.length; i++)
                console.log($selection[i].id);          // s1
        </script>

The parent method

The parent method returns a set consisting of the parent elements of the elements in the set.

The syntax is: var $selection = jQuerySet.parent([selector]);. An example:


        <div id="d0">
            <span id="s0"></span>    
            <span id="s1"><span id="s2"></span></span>
        </div>
        <div id="d1">
            <span id="s3"></span>
        </div>
        <p id="p0">
            <span id="s4"></span>
        </p>
        <script>
            var spans = jQuery("span");                 // 5 span elements
            var $selection = spans.parent("div, span");
            for (var i = 0; i < $selection.length; i++)
                console.log($selection[i].id);          // d0, s1, d1
        </script>

In the above example, the parents of all five span elements are retrieved, if they are of type div or span. The d0 element is retrieved only once, although it is the parent of two elements. The p0 element is not retrieved, because it is not a div or span.

The parents method

The name of the method is a bit of a misnomer, because the parents method returns a set consisting of the ancestor elements of the elements in the set, not only the immediate parents.

The syntax is: var $selection = jQuerySet.parents([selector]);. An example:


        <body id="body">
            <script src="jquery-2.1.4.js"></script>
            <div id="d0">
                <span id="s0"></span>        
                <span id="s1"><span id="s2"></span></span>
            </div>
            <script>
                var spans = jQuery("#s1, #s2");             // 2 span elements
                var $selection = spans.parents(":not(:root)");
                for (var i = 0; i < $selection.length; i++)
                    console.log($selection[i].id);          // s1, d0, body
            </script>
        </body>

In the example, the ancestors of the s1 and s2 elements are retrieved. The root html element (not shown) is excluded by using the :not(:root) selector.

The parentsUntil method

This method returns the ancestors of elements, all the way up the DOM tree, until a certain element or condition is met. The optional selector argument can be a query string, a set of DOM elements or a jQuery set. The optional filter argument is a query expression and can be used to filter out elements satisfying the filter.

The syntax is: var $selection = jQuerySet.parentsUntil([selector, [filter]]);. The following example retrieves ancestors up to, but not including, the root html element (not shown). In addition, div elements are excluded by using the filter argument:


        <body id="body">
            <script src="jquery-2.1.4.js"></script>
            <div id="d0">
                <span id="s0"></span>        
                <span id="s1"><span id="s2"></span></span></
            div>
            <script>
                var htmlNodes = document.getElementsByTagName("html");
                var spans = jQuery("#s1, #s2");                             // 2 span elements
                var $selection = spans.parentsUntil(htmlNodes, ":not(div)");
                for (var i = 0; i < $selection.length; i++)
                    console.log($selection[i].id);                          // s1, body
            </script>
        </body>

The offsetParent method

This method returns the closest positioned ancestor (or the document root) of the elements in the set. A positioned element is an element that has style.position equal to relative, absolute or fixed. This information can be useful for calculating offsets for performing animations and placing objects on the page.

The syntax is: var $selection = jQuerySet.offsetParent();. The following example retrieves positioned ancestors of two elements. One of the input elements has no positioned ancestor, and thus the root html node is also added to the result set.


        <html id="html" lang="en">
            <head>
                <meta charset="utf-8"></meta>        
                <title></title>
            </head>    
            <body>
                <script src="jquery-2.1.4.js"></script>
                <div id="d0" style="position:relative;left:10px;">
                    <span>
                        <span id="s2"></span>
                    </span>
                </div>
                <script>
                    var elements = jQuery("#d0, #s2");
                    var $selection = elements.offsetParent();
                    for (var i = 0; i < $selection.length; i++)
                        console.log($selection[i].id);              // html, d0 (d0 is the positioned ancestor of s2)
                </script>
            </body>
        </html>

The closest method

This method returns the closest ancestor satisfying a condition, specified via the selector argument.

The syntax is: var $selection = jQuerySet.closest([selector]);. The following example retrieves the closest ancestor which is of type div:


        <div id="d0">
            <span id="s0"></span>    
            <span id="s1"><span id="s2"></span></span>
        </div>
        <script>
            var s2 = jQuery("#s2");
            var $selection = s2.closest("div");
            for (var i = 0; i < $selection.length; i++)
                console.log($selection[i].id);          // d0
        </script>

The siblings method

This method returns the siblings of elements, optionally filtered through the selector argument.

The syntax is: var $selection = jQuerySet.siblings([selector]);. The following example retrieves the siblings of a span element, filtered by tag name.


        <div>
            <span id="s0"></span>    
            <span id="s1"></span>    
            <span id="s2"></span>    
            <p id="p0"></p>
        </div>
        <script>
            var spanS1 = jQuery("#s1");
            var $selection = spanS1.siblings(":not(p)");
            for (var i = 0; i < $selection.length; i++)
                console.log($selection[i].id);              // s0, s2
        </script>

The next method

This method returns the immediately following sibling of elements, optionally filtered through the selector argument.

The syntax is: var $selection = jQuerySet.next([selector]);. The following example retrieves the neighboring sibling of two elements.


        <div>
            <span id="s0"></span>    
            <span id="s1"></span>    
            <span id="s2"></span>    
            <span id="s3"></span>    
            <span id="s4"></span>
        </div>
        <script>
            var spans = jQuery("#s1, #s2");
            var $selection = spans.next();
            for (var i = 0; i < $selection.length; i++)
                console.log($selection[i].id);              // s2, s3
        </script>

The nextAll method

This method returns the following sibling of elements, i.e. the siblings that come after the element(s) in question. The query can be optionally filtered through the selector argument.

The syntax is: var $selection = jQuerySet.nextAll([selector]);. The following example retrieves the following sibling of two elements.


        <div>
            <span id="s0"></span>
            <span id="s1"></span>
            <span id="s2"></span>    
            <span id="s3"></span>    
            <span id="s4"></span>
        </div>
        <script>
            var spans = jQuery("#s1, #s2");
            var $selection = spans.nextAll();
            for (var i = 0; i < $selection.length; i++)
                console.log($selection[i].id);              // s2, s3, s4
        </script>

The nextUntil method

This method returns the following sibling of elements, i.e. the siblings that come after the element(s) in question, until another specified element is found. The selector argument can contain a query expression or a set of elements. The query can be optionally filtered through the filter argument.

The syntax is: var $selection = jQuerySet.nextUntil([selector[, filter]]);. The following example retrieves the following sibling of an element, until the element with id s3.


        <div>
            <span id="s0"></span>
            <span id="s1"></span>
            <span id="s2"></span>    
            <span id="s3"></span>    
            <span id="s4"></span>
        </div>
        <script>
            var spanS0 = jQuery("#s0");
            var spanS3 = jQuery("#s3");
            var $selection = spanS0.nextUntil(spanS3);
            for (var i = 0; i < $selection.length; i++)
                console.log($selection[i].id);              // s1, s2
        </script>

The prev method

This method returns the sibling that comes immediately before a specified element, optionally filtered through the selector argument.

The syntax is: var $selection = jQuerySet.prev([selector]);. The following example retrieves the neighboring, previous sibling of two elements.


        <div>
            <span id="s0"></span>
            <span id="s1"></span>
            <span id="s2"></span>    
            <span id="s3"></span>    
            <span id="s4"></span>
        </div>
        <script>
            var spans = jQuery("#s3, #s2");
            var $selection = spans.prev();
            for (var i = 0; i < $selection.length; i++)
                console.log($selection[i].id);              // s1, s2
        </script>

The prevAll method

This method returns the siblings that come before a specified element. The query can be optionally filtered through the selector argument.

The syntax is: var $selection = jQuerySet.prevAll([selector]);. The following example retrieves the previous siblings of two elements.


        <div>
            <span id="s0"></span>
            <span id="s1"></span>
            <span id="s2"></span>    
            <span id="s3"></span>    
            <span id="s4"></span>
        </div>
        <script>
            var spans = jQuery("#s3, #s2");
            var $selection = spans.prevAll();
            for (var i = 0; i < $selection.length; i++)
                console.log($selection[i].id);              // s2, s1, s0
        </script>

The prevUntil method

This method returns the siblings that come immediately before the specified element, until another specified element is found. The selector argument can contain a query expression or a set of elements. The query can be optionally filtered through the filter argument.

The syntax is: var $selection = jQuerySet.prevUntil([selector[, filter]]);. The following example retrieves the previous sibling of an element, until the element with id s1.


        <div>
            <span id="s0"></span>
            <span id="s1"></span>
            <span id="s2"></span>    
            <span id="s3"></span>
            <span id="s4"></span>
        </div>
        <script>
            var spanS4 = jQuery("#s4");
            var spanS1 = jQuery("#s1");
            var $selection = spanS4.prevUntil(spanS1);
            for (var i = 0; i < $selection.length; i++)
                console.log($selection[i].id);              // s3, s2
        </script>

The add method

This method can be used to add elements to an existing jQuery set. The method returns a new jQuery set containing the added elements as well as the original ones. The syntax is: var $selection = jQuerySet.add([selector[, context]]);. The method is quite versatile, in that it accepts a range of types as its first parameter:

A string containing a query expression. The elements that satisfy the query will be added to the result set.
A string containing html. The elements will be created as DOM elements, but will not actually be added to the DOM document.
A DOM element or an array of these.
A jQuery object.

When you pass a query expression in the first argument, the context parameter can be used to narrow the search. This parameter also accepts different types:

A string containing a query expression. The elements that satisfy the query will be added to the result set.
A DOM element or an array of these.
A jQuery object.

This parameter works by limiting which elements can be added to the result set in that only descendants of elements specified via the context parameter will actually be added.

The following snippet exemplifies using query expressions for both of the parameters:


        <div id="d0">
            <p>
                <span id="s0"></span>        
                <span id="s1"></span>
            </p>
        </div>
        <div id="d1">
            <span id="s2"></span>
        </div>
        <span id="s3"></span>
        <span id="s4"></span>
        <script>
            var $s3 = jQuery("#s3");                    // A set containing s3
            var $selection = $s3.add("span", "div");    // Add span elements having an ancestor div
            for (var i = 0; i < $selection.length; i++)
                console.log($selection[i].id);          // s0, s1, s2, s3
        </script>

The not method

This method can be used to remove elements from an existing jQuery set. The method returns a new jQuery set containing the remaining elements. The syntax is: var $selection = jQuerySet.not([selector]);. Elements specified in the parameter are removed from the result set. The method is quite versatile, in that it accepts a range of types in its parameter:

A string containing a query expression. The elements that satisfy the query will be removed from the result set.
A DOM element or an array of these.
A jQuery object.
A function that returns a boolean - returning true causes an element to be removed.

The following snippet exemplifies using an element array to specify elements to remove:


        <div id="d0">
            <span id="s0"></span>    
            <span id="s1"></span>
        </div>
        <span id="s3"></span>
        <span id="s4"></span>
        <script>
            var $spans = jQuery("span");                        // All span
            var s0s1 = document.getElementById("d0").children;  // s0 and s1
            var $selection = $spans.not(s0s1);                  // remove s0 and s1
            for (var i = 0; i < $selection.length; i++)
                console.log($selection[i].id);
        </script>

The next example shows how to use a function to determine which elements to remove. The function will be called for every element in the set, and the this variable will be set to reference that element. In addition, the function receives an index argument, which is an integer indicating the 0-based index of the element in the set. Returning true from the function causes the element to be removed.


        <div id="d0">
            <span id="s0"></span>    
            <span id="s1"></span>
        </div>
        <span id="s2"></span>
        <span id="s3"></span>
        <script>
            var $spans = jQuery("span");                        // All span
            var $selection = $spans.not(
                function (index)
                {
                    return this.parentElement.nodeName == "DIV" && index > 0;
                }
            );
            for (var i = 0; i < $selection.length; i++)
                console.log($selection[i].id);                  // s0, s2, s3
        </script>

The filter method

This method is a mirror image of the not method in that elements not specified in the parameter are removed from the result set. The syntax is: var $selection = jQuerySet.filter([selector]); and the same types go into this parameter as with the not method.

The slice method

This method can be used to remove elements from an existing jQuery set, based on index. The method returns a new jQuery set containing the remaining elements. The syntax is: var $selection = jQuerySet.slice(start[, end]);. The start parameter represents the index of the first element to be included in the result, and the end parameter indicates the index of the first element not to be included, e.g. calling jQuerySet.slice(0, 1) gives you a result containing just the first element. If the last parameter is omitted, all remaining elements are included in the result. An example:


        <span id="s0"></span>
        <span id="s1"></span>
        <span id="s2"></span>
        <span id="s3"></span>
        <script>
            var $spans = jQuery("span");                        // All span
            var $selection = $spans.slice(1, 3);                // keep # 1 and 2
            for (var i = 0; i < $selection.length; i++)
                console.log($selection[i].id);                  // s1, s2
        </script>

The has method

This method removes elements from an existing jQuery set that don't have as children one or more of the elements specified in the argument. The syntax is: var $selection = jQuerySet.has(selector);. The selector argument can be a jQuery expression, a jQuery set, an array of elements or a single element. An example:


        <div id="d0">
            <span id="s0"></span>    
            <span id="s1"></span>
        </div>
        <div id="d1"></div>
        <span id="s2"></span>
        <script>
            var $divs = jQuery("div");                                          // All div
            var $selection = $divs.has(document.getElementsByTagName("span"));  // only div with span
            for (var i = 0; i < $selection.length; i++)
                console.log($selection[i].id);                                  // d0
        </script>

The map method

The map method lets you select a value from each element in a set into a new set. The syntax is: var $selection = jQuerySet.map(function(index, element));. The function that is passed in takes the element index as its first argument and a reference to the element as its second. In addition, the this variable will also point to the element in question. An example that collects the id values from elements:


        <span id="s0"></span>
        <span id="s1"></span>
        <span id="s2"></span>
        <script>
            var $spans = jQuery("span");                            // All span
            var ids = $spans.map(function (index, element)
                {
                    return this.id;                                 // select element.id
                }
            );
            for (var i = 0; i < ids.length; i++)
                console.log(ids[i]);                         // s0, s1, s2
        </script>

The each method

The each method lets you iterate over each element in the set, using a callback function, which is called for each iteration. The syntax is: var $selection = jQuerySet.each(function(index, element));. The function that is passed in takes the element index as its first argument and a reference to the element as its second. In addition, the this variable will also point to the element in question. An example that logs the id values of elements to the console:


        <span id="s0"></span>
        <span id="s1"></span>
        <span id="s2"></span>
        <script>
            var $spans = jQuery("span");                           // All span
            var $selection = $spans.each(function (index, element)
                {
                    console.log(element.id + ' ' + index);         // s0 0, s1 1, s2 2
                }
            );
        </script>

The is method

This method returns a boolean indicating if one or more of the passed-in elements exist in a jQuery set. The syntax is: var aBoolean = jQuerySet.is([selector]);. The method accepts a range of types in its parameter:

A string containing a query expression.
A jQuery object.
An element reference or an array of these.
A function that returns a boolean.

An example:


        <span id="s0"></span>
        <span id="s1"></span>
        <span id="s2"></span>
        <script>
            var $spans = jQuery("span");        // All span
            var exists = $spans.is("#s2");
            console.log(exists);            // true - contains #s2
        </script>

Next chapter