This is documentation on the Sizzle Selector Engine. For more information please visit:

• Sizzle Project Home Page
• Sizzle Source Repository
• Sizzle Discussion Group

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 notable exceptions to the CSS 3 selector support (the reasoning for this decision can be found here):

• :root
• :target
• :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): Sizzle supports non-simple selectors in :not() (most browsers only support :not(a), for example).
• :not(div > p): Sizzle supports full selectors in :not().
• :not(div, p): Sizzle supports multiple selectors in :not().
• [NAME=VALUE]: Sizzle doesn’t require quotes around the specified value in an attribute selector.

Additions

• [NAME!=VALUE]: Finds all elements whose NAME attribute doesn’t match the specified value. Is equivalent to doing :not([NAME=VALUE]).
• :contains(TEXT): Finds all elements whose textual context contains the word ‘TEXT’ (case sensitive).
• :header: Finds all elements that are a header element (h1, h2, h3, h4, h5, h6).
• :parent: Finds all elements that contains another element.

Positional Selector Additions

• :first/:last: Finds the first or last matching element on the page. (e.g. “div:first” would find the first div on the page, in document order)
• :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 you, or 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 )

The primary method of calling Sizzle – pass in a selector and an optional context (if no context is provided the root ‘document’ is used). Runs the specified selector and returns an array of matched DOMElements.

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

An alternative to the previous method of calling Sizzle – pass in an existing array and the results will be appended on to that array.

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

Takes in a set of DOMElements, filters them against the specified selector, and returns the results. The selector can be a full selector (e.g. “div > span.foo”) and not just a fragment.

Internal API

Note: Sizzle.find and Sizzle.filter are primarily internally-used methods. Most functionality should be used through Sizzle and Sizzle.matches.

Sizzle.find( String selector, DOMElement context, Boolean isXML )

Taking a selector and a context, finds a set of matching elements. ‘isXML’ is a boolean letting you know if the ‘find’ is happening against an XML document. The return result from the method is an object that has two properties: ‘set’ (an array of the DOM elements found) and ‘expr’ (the remaining portion of the selector).

For example, given the following selector: “div > span#foo” the return result from Sizzle.find might be: { set: [], expr: "div > span" }.

Sizzle.filter( String selector, Array<DOMElement> set, Boolean inplace, Boolean not )

Takes in an array of DOMElements and returns a new array of elements, filtered to removed elements that don’t match the selector. This is different from Sizzle.matches in that it only works on simple selectors (e.g. it works on ‘div.foo’ but not on ‘div div’). Setting ‘inplace’ to true will change the results on the incoming ‘set’ array, setting ‘not’ to true will invert the results.

Extension API

Sizzle.selectors.match = { NAME: RegExp }

A collection of regular expressions to be used for finding or filtering elements. 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 an order hook to ‘order’.

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

Sizzle.selectors.order = [ 'NAME', 'NAME2', ... ]

Specifies the order in which ‘find’ functions should be tried. For example, the typical default specifies ‘ID’ as going first (since this is both the fastest method and is most likely to trim to results down to their smallest amount (either 0 or 1 elements).

Sizzle.selectors.relative = { TOKEN: function( set, selector, isXML ) }

Filter the set of elements based upon the relatively-positioned selector. For example a token might be “+” (for the immediately adjacent element) and a selector might be “div.class”. ‘isXML’ refers to if the querying is being done in an XML document. The job of the relative function is to modify the incoming set (array of DOMElements) in place. If an element matches the specified selector then the newly-matched element should be inserted. If there is no match for the selector than the value ‘false’ should be inserted.

For example, the following relative function would return elements whose previous node is a div element:

function( set, selector ) {
  for ( var i = 0, l = set.length; i < l; i++ ) {
    set[i] = set[i] && set[i].previousSibling && set[i].previousSibling.nodeName.toUpperCase() === "DIV" ? 
      set[i].previousSibling :
      false;
  }
}

As of right now there is no way to add in custom relative selectors – only modify existing ones.

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

Filter an element against the regular expression results (which will be the pre-processed results from the preFilter function, if specified). The return result should be true or false (corresponding to if the element matches the selector).

Attributes

Sizzle.selectors.attrMap = { NAME: "OTHERNAME" }

For non-XML documents – maps DOM attribute names from one to another (e.g. ‘for’ maps to ‘htmlFor’).

Sizzle.selectors.attrHandle = { NAME: function( elem ) }

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.filters = { NAME: function( elem, pos, match ) }

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). ‘pos’ is the position of the selector in full set of elements (and is optional) and ‘match’ is the returned array from the matching regular expression (‘match³’ will contain the contents of a :foo(bar) style pseudo-selector). Both ‘pos’ and ‘match’ are optional.

For example, this is a simple pseudo-selector:

Sizzle.selectors.filters.hidden = function(elem){
  return elem.offsetWidth === 0 || elem.offsetHeight === 0;
};

Sizzle.selectors.setFilters = { NAME: function( elem, pos, match, set ) }

Works very similarly to normal pseudo-selectors but work explicitly with the specified positional pseudo-selectors (like :first, :last, and :eq). ‘set’ contains an array of all the elements that are being filtered – to be used as a reference, not to be modified.