Skip to content
This repository


Project Home Page | Source Repository | Google Group Discussion

Browser Support

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.0+
  • Chrome 5+
  • Safari 4+
  • Opera 10.6+

To report a bug in any of these browsers, please add an issue with a test case from jsfiddle or jsbin.

Selectors

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 :visited and 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 :even would 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 (:button also finds button elements).

API

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

Public API

Sizzle( String selector[, DOMElement|DOMDocument context[, Array results]] )

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

Sizzle.matchesSelector( DOMElement element, String selector )

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

Sizzle.matches( String selector, Array<DOMElement> elements )

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.

Internal API

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.

Sizzle.compile( selector )

This method can be called to add a selector to the internal cache of compiled selectors to be used in a later selection. For instance, if writing a plugin, you may find it useful to add a custom selector you know will be used by the user at a later time. Call Sizzle.compile(":myCustomPseudo") and it's cached.

Sizzle.selectors.cacheLength = Number

Most of the time, it should not be necessary to adjust the size of the selector cache. However, the size of the internal cache can be adjusted to hold more or less compiled selector functions. The default is currently 50.

returns(Function): The compiled function to be used when filtering the set of possibly matching elements.

Parameters

selector: A css selector

context: The context from which to base the selector. While this argument is required, this can often just be document.

isXML: A Boolean indicating whether or not the current context is xml. The default is false.


Extension API

Sizzle.selectors.match.NAME = RegExp

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.

Finding

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.

Sizzle.selectors.find.NAME = function( match, context, isXML ) {}

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.

Filtering

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.

Sizzle.selectors.preFilter.NAME = function( match ) {}

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.

Sizzle.selectors.filter.NAME: function( element, match[1][, match[2], match[3], ...] ) {}

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

Attributes

Sizzle.selectors.attrHandle.LOWERCASE_NAME = function( elem, casePreservedName, isXML ) {}

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.

Pseudo Selectors

Sizzle.selectors.pseudos.NAME = function( elem ) {}

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;
};

Sizzle.selectors.createPseudo(function)

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 );
    };
});

Backwards-compatible plugins for pseudos with arguments

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 );

Sizzle.selectors.setFilters.LOWERCASE_NAME = function( elements, argument, not ) {}

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> ]

Thanks

Special thanks goes out to these folks. Without their contributions to the open source community, Sizzle would not be what it is today.

Something went wrong with that request. Please try again.