Filtering methods
These methods remove elements from the set matched by a jQuery object.
.filter()
Note
Reduce the set of matched elements to those that match the selector or pass the function's test.
.filter(selector) .filter(function)
Parameters (first version)
selector: A string containing a selector expression to match elements against
Parameters (second version)
function: A function used as a test for each element in the set
Return value
The new jQuery object.
Description
Given a jQuery object that represents a set of DOM elements, the .filter() method constructs a new jQuery object from a subset of the matching elements. The supplied selector is tested against each element; all elements matching the selector will be included in the result.
Consider a page with a simple list as follows:
<ul> <li>list item 1</li> <li>list item 2</li> <li>list item 3</li> <li>list item 4</li> <li>list item 5</li> <li>list item 6</li> </ul>
We can apply this method to the set of list items like this:
$('li').filter(':even').css('background-color', 'red');
The result of this call is a red background for the items 1, 3, and 5, as they match the selector. (Recall that :even and :odd use 0-based indexing.)
Using a filter function
The second form of this method allows us to filter elements against a function rather than a selector. If the function returns true for an element, the element will be included in the filtered set; otherwise, it will be excluded. Suppose we have a somewhat more involved HTML snippet as follows:
<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>
<li>list item 6</li>
</ul>
In such a case, we can select the list items and then filter them based on their contents:
$('li').filter(function(index) {
return $('strong', this).length == 1;
}).css('background-color', 'red');
This code will alter only the first item in the list as it contains exactly one <strong> tag. Within the filter function, this refers to each DOM element in turn. The parameter passed to the function tells us the index of that DOM element within the set matched by the jQuery object.
We can also take advantage of the index parameter passed through the function, which indicates the 0-based position of the element within the unfiltered set of the matched elements.
$('li').filter(function(index) {
return index % 3 == 2;
}).css('background-color', 'red');
This alteration to the code will cause items 3 and 6 to be highlighted, as it uses the modulus operator (%) to select every item with an index value that, when divided by 3, has a remainder of 2.
.not()
Note
Remove elements from the set of matched elements.
.not(selector) .not(elements) .not(function)
Parameters (first version)
selector: A string containing a selector expression to match elements against
Parameters (second version)
elements: One or more DOM elements to remove from the matched set
Parameters (third version)
function: A function used as a test for each element in the set
Return value
The new jQuery object.
Description
Given a jQuery object that represents a set of DOM elements, the .not() method constructs a new jQuery object from a subset of the matching elements. The supplied selector is tested against each element; the elements that don't match the selector will be included in the result.
Consider a page with a simple list as follows:
<ul> <li>list item 1</li> <li>list item 2</li> <li>list item 3</li> <li>list item 4</li> <li>list item 5</li> </ul>
We can apply this method to the set of list items.
$('li').not(':even').css('background-color', 'red');
The result of this call is a red background for items 2 and 4, as they do not match the selector. (Recall that :even and :odd use 0-based indexing.)
Removing specific elements
The second version of the .not() method allows us to remove elements from the matched set, assuming we have found those elements previously by some other means. For example, suppose our list had an ID applied to one of its items as follows:
<ul> <li>list item 1</li> <li>list item 2</li> <li id="notli">list item 3</li> <li>list item 4</li> <li>list item 5</li> </ul>
We can fetch the third item in the list using the native JavaScript getElementById() function, and then remove it from a jQuery object.
$('li').not(document.getElementById('notli'))
.css('background-color', 'red');
This statement changes the color of items 1, 2, 4, and 5. We could have accomplished the same thing with a simpler jQuery expression, but this technique can be useful when, for example, other libraries provide references to plain DOM nodes.
As of jQuery 1.4, the .not() method can take a function as its argument in the same way that .filter() does. Elements for which the function returns true are excluded from the filtered set; all other elements are included.
.has()
Note
Reduce the set of matched elements to those that have a descendant that matches the selector.
.has(selector)
Parameters
selector: A string containing a selector expression to match elements against
Return value
The new jQuery object.
Description
Given a jQuery object that represents a set of DOM elements, the .has() method constructs a new jQuery object from a subset of the matching elements. The supplied selector is tested against the descendants of the matching elements; the element will be included in the result if any of its descendant elements matches the selector.
Consider a page with a nested list as follows:
<ul>
<li>list item 1</li>
<li>list item 2
<ul>
<li>list item 2-a</li>
<li>list item 2-b</li>
</ul>
</li>
<li>list item 3</li>
<li>list item 4</li>
</ul>
We can apply this method to the set of list items as follows:
$('li').has('ul').css('background-color', 'red');
The result of this call is a red background for item 2, as it is the only <li> that has a <ul> among its descendants.
.eq()
Note
Reduce the set of matched elements to the one at the specified index.
.eq(index)
Parameters
index: An integer indicating the 0-based position of the element
Return value
The new jQuery object.
Description
Given a jQuery object that represents a set of DOM elements, the .eq() method constructs a new jQuery object from one of the matching elements. The supplied index identifies the position of this element in the set.
Consider a page with a simple list as follows:
<ul> <li>list item 1</li> <li>list item 2</li> <li>list item 3</li> <li>list item 4</li> <li>list item 5</li> </ul>
We can apply this method to the set of list items as follows:
$('li').eq(2).css('background-color', 'red');
The result of this call is a red background for item 3. Note that the supplied index is 0-based, and refers to the position of the element within the jQuery object, not within the DOM tree.
If a negative number is provided, this indicates a position starting from the end of the set, rather than the beginning. For example:
$('li').eq(-2).css('background-color', 'red');
The result of this call is a red background for item 4, as it is second from the end of the set.
.first()
Note
Reduce the set of matched elements to the first in the set.
.first()
Parameters
None
Return value
The new jQuery object.
Description
Given a jQuery object that represents a set of DOM elements, the .first() method constructs a new jQuery object from the first matching element.
Consider a page with a simple list as follows:
<ul> <li>list item 1</li> <li>list item 2</li> <li>list item 3</li> <li>list item 4</li> <li>list item 5</li> </ul>
We can apply this method to the set of list items as follows:
$('li').first().css('background-color', 'red');
The result of this call is a red background for item 1.
.last()
Note
Reduce the set of matched elements to the final one in the set.
.last()
Parameters
None
Return value
The new jQuery object.
Description
Given a jQuery object that represents a set of DOM elements, the .last() method constructs a new jQuery object from the first matching element.
Consider a page with a simple list as follows:
<ul> <li>list item 1</li> <li>list item 2</li> <li>list item 3</li> <li>list item 4</li> <li>list item 5</li> </ul>
We can apply this method to the set of list items as follows:
$('li').last().css('background-color', 'red');
The result of this call is a red background for the final list item.
.slice()
Note
Reduce the set of matched elements to a subset specified by a range of indices.
.slice(start[, end])
Parameters
start: An integer indicating the 0-based position after which the elements are selectedend(optional): An integer indicating the 0-based position before which the elements stop being selected; if omitted, the range continues until the end of the set
Return value
The new jQuery object.
Description
Given a jQuery object that represents a set of DOM elements, the .slice() method constructs a new jQuery object from a subset of the matching elements. The supplied start index identifies the position of one of the elements in the set. If end is omitted, all of the elements after this one will be included in the result.
Consider a page with a simple list as follows:
<ul> <li>list item 1</li> <li>list item 2</li> <li>list item 3</li> <li>list item 4</li> <li>list item 5</li> </ul>
We can apply this method to the set of list items as follows:
$('li').slice(2).css('background-color', 'red');
The result of this call is a red background for the items 3, 4, and 5. Note that the supplied index is 0-based, and refers to the position of elements within the jQuery object; not within the DOM tree.
The end parameter allows us to limit the selected range even further. For example:
$('li').slice(2, 4).css('background-color', 'red');
Now only items 3 and 4 are selected. The index is once again 0-based. The range extends up to, but doesn't include, the specified index.
Negative indices
The jQuery .slice() method is patterned after the JavaScript .slice() method for arrays. One of the features that it mimics is the ability for negative numbers to be passed as either the start or end parameter. If a negative number is provided, this indicates a position starting from the end of the set, rather than the beginning. For example:
$('li').slice(-2, -1).css('background-color', 'red');
This time only the list item 4 turns red, as it is the only item in the range between the second from the end (-2) and the first from the end (-1).