-
Notifications
You must be signed in to change notification settings - Fork 956
Home
[Project Home Page](http://sizzlejs.com/) | [Source Repository](http://github.com/jquery/sizzle/) | [Google Group Discussion](http://groups.google.com/group/sizzlejs)
Note: Sizzle's browser support may differ from the browser support of libraries that use Sizzle. Reporting issues on Sizzle's issue tracker rather than on library bug trackers will increase the probability that an issue will be addressed.
Sizzle supports:
- IE6+
- FF3.6+
- Chrome 14+
- Safari 4.0+
- Opera 11.6+ (should work on 10.6 too but it is not regularly tested on this version)
- iOS 5.1+
- Anroid 2.3, 4.0+
To report a bug in any of these browsers, please add an issue with a test case from jsfiddle or jsbin.
Sizzle supports virtually all CSS 3 Selectors - this even includes some parts that are infrequently implemented such as escaped selectors (".foo\+bar"), Unicode selectors, and results returned in document order. There are a few exceptions to CSS3 selector support. These exceptions are only limited to selectors that would require events added to the DOM to keep track of the state of elements. For instance, the following pseudo-selectors are not supported:
:hover:active:visited-
:link(this is the opposite of:visitedand also requires an event)
Note: Some CSS3 selectors were not supported until version 1.9. These were added in 1.9:
:target:root:nth-last-child-
:nth-of-type/:nth-last-of-type/:first-of-type/:last-of-type/:only-of-type :lang()
In addition to the CSS 3 Selectors Sizzle supports the following additional selectors or conventions.
Changes
-
:not(a.b),:not(div > p),:not(div, p): Sizzle supports complex selectors in:not()(most browsers only support:not(a), for example). -
:not(:not(a)),:not(:has(div:first-child)): Sizzle supports nested pseudos.
Additions
-
[NAME!=VALUE]: Finds all elements whose NAME attribute doesn't match the specified value. Is equivalent to:not([NAME=VALUE]). -
:contains(TEXT): Finds all elements whose textual context contains the word 'TEXT' (case-sensitive). -
:header: Finds all elements that are header elements (h1, h2, h3, h4, h5, h6). -
:parent: Finds all elements that contain another element.
Positional Selector Additions
The word positional here refers to an element's placement in the set after a selection, based on document order. For instance, div:first would return an array containing the first div on the page and div:first em would initially get the first div on the page, then all of the em's within that div. This works by first doing a selection for divs, retrieving the first one from that set, then using that div as the context for finding all em's. Note that all positional selectors are zero-indexed (corresponding to array positions).
-
:first/:last: Finds the first or last matching element on the page. -
:even/:odd: Finds every other element on the page (counting begins at 0, so:evenwould match the first element). -
:eq/:nth: Finds the nth element on the page (e.g.:eq(5)finds the 6th element on the page). -
:lt/:gt: Finds all elements at positions less than or greater than the specified positions.
Form Selector Additions
-
:input: Finds all input elements (includes textareas, selects, and buttons). -
:text,:checkbox,:file,:password,:submit,:image,:reset,:button: Finds the input element with the specified input type (:buttonalso finds button elements).
The Sizzle API is broken up into a couple portions: Public API (which is what most users will interact with), Internal API (some additional methods used internally by Sizzle), and Extension API (a series of extension points upon which the selector engine can be modified).
This is the main function for finding elements. It will use querySelectorAll if available.
returns (Array): all of the elements matching the selector
Parameters
selector: A css selector
context: An element or document to use as the context for finding elements. The default is the current document.
results: Optionally pass an array or array-like object to which Sizzle will append the elements (for instance, jQuery passes the jQuery object here). An array-like object is defined as an object containing elements with an accurate length property and a push method for adding elements to the object.
Uses native matchesSelector if available.
returns(Boolean): whether the given element matches the selector
Parameters
element: A DOMElement against which Sizzle will test the selector
selector: A css selector
returns(Array): All the elements in the set that match the given selector.
Parameters
selector: A css selector
elements: An array of DOMElements to filter against the specified selector.
Note: Most functionality should be used through the above Public API. The internal API is meant primarily for internal use, but is exposed just in case you have need for it.
Internal caches hold compiled selector functions and tokenization objects. Their initial size is currently 50, but can be set to any positive number.
This method compiles a selector function and caches it for later use. For instance, you may want to call Sizzle.compile(".myWidget:myPseudo") during initialization of a plugin to save some time during the first selection of matching elements.
returns(Function): The compiled function to be used when filtering the set of possibly matching elements.
Parameters
selector: A css selector
This contains the regular expressions used to parse a selector into different parts to be used for finding and filtering. The name of each of the regular expressions should correspond to the names specified in the Sizzle.selectors.find and Sizzle.selectors.filter objects.
In order to add a new find function you'll need to add a regular expression to match, a function to find, and add "|" + NAME to the Sizzle.selectors.order regex.
A method for finding some elements on a page. The specified function will only be called, at most, once per selector. match is the array of results returned from matching your specified regular expression against the selector, context is the DOMElement or DOMDocument from which selection will occur, and isXML is a boolean value letting you know if you're currently operating within an XML document.
To add a new filtering statement you'll need to add a regular expression to the match object, and optional function to preFilter, and a function to filter.
An optional pre-filter function which allows you to examine the matched array from the corresponding regular expression and return a new matched array (which will be passed and flattened as arguments to the corresponding filter function). This allows you to remove some of the repetitive processing that might need to occur in a filter function.
The arguments for a filter method are the element and the captures from the regex corresponding to this filter (indicated above by what is in the match, starting at index 1 since index 0 is popped off before passed to any filter). The return result should be true or false (corresponding to if the element matches the selector).
Handle an attribute that needs to be tackled in a particular manner (like 'href', which has fun cross-browser issues). The return result should be the actual string value of that attribute.
The most common extension to a selector engine: adding a new pseudo-selector. The return result from this function should be a boolean (true if the element matches the selector, false if not).
For example, this is a simple pseudo-selector:
Sizzle.selectors.filters.hidden = function( elem ) {
return elem.offsetWidth === 0 || elem.offsetHeight === 0;
};Note that in jQuery 1.8, the old API for creating custom pseudos with arguments was broken, but in jQuery 1.8.1+, the API is backwards-compatible. Regardless, the use of createPseudo is greatly encouraged.
createPseudo need only be used if your custom pseudo accepts an argument. With the parser now compiling a function of functions, creating custom pseudos with arguments is much cleaner. For example, within Sizzle, the implementation for the :not pseudo selector is very similar to:
Sizzle.selectors.pseudos.not =
Sizzle.selectors.createPseudo(function( selector /* the argument for not */ ) {
var matcher = Sizzle.compile( selector );
return function( elem ) {
return !matcher( elem );
};
});In jQuery, this would be equivalent to:
jQuery.expr[":"].not = jQuery.expr.createPseudo(function( selector ) {
var matcher = jQuery.find.compile( selector );
return function( elem ) {
return !matcher( elem );
};
});To write a custom selector with arguments that can take advantage of the new API and still support all versions of Sizzle, one need only check for the presence of the createPseudo method. The following example uses jQuery syntax. Live example
// An implementation of a case-insensitive contains pseudo
// made for all versions of jQuery
(function( $ ) {
function icontains( elem, text ) {
return (
elem.textContent ||
elem.innerText ||
$( elem ).text() ||
""
).toLowerCase().indexOf( (text || "").toLowerCase() ) > -1;
}
$.expr[':'].icontains = $.expr.createPseudo ?
$.expr.createPseudo(function( text ) {
return function( elem ) {
return icontains( elem, text );
};
}) :
function( elem, i, match ) {
return icontains( elem, match[3] );
};
})( jQuery );These filters are run after a previous part of a selector has already returned results and you'd like to reduce the set somehow. setFilters are found from matching Sizzle.selectors.match.POS. The argument for any setFilter accepting an argument is expected to be a digit. The not argument indicates whether or not the result should be opposite of what they are normally (as in div:not(:first)). For example, the code for the :first setFilter is similar to:
var first = function( elements, argument, not ) {
// No argument for first
return not ? elements.slice( 1 ) : [ elements[0] ];
};
Sizzle.selectors.setFilters.first = first;It is easy to extend Sizzle, even Sizzle's POS selectors. Here is an example of changing the name of :first to :uno.
Sizzle.selectors.match.POS = new RegExp( oldPOS.source.replace("first", "uno"), "gi" );
Sizzle.selectors.setFilters.uno = Sizzle.selectors.setFilters.first;
delete Sizzle.selectors.setFilters.first;
Sizzle("div:uno"); // ==> [ <div> ]Special thanks goes out to these folks. Without their contributions to the open source community, Sizzle would not be what it is today.
- Diego Perini and NWMatcher
- The creators of the Slick selector engine used in mootools
- Samuel Lebeau for writing bouncer, a small bottom-up element matcher