W3C

Selectors API Level 2

W3C Working Draft 28 June 2012

This Version:
http://www.w3.org/TR/2012/WD-selectors-api2-20120628/
Latest Editor's Draft:
http://dev.w3.org/2006/webapi/selectors-api2/
Latest Version:
http://www.w3.org/TR/selectors-api2/
Previous Versions:
http://www.w3.org/TR/2010/WD-selectors-api2-20100119/
Editors:
Lachlan Hunt (Opera Software ASA) <lachlan.hunt@lachy.id.au>

Abstract

Selectors, which are widely used in CSS, are patterns that match against elements in a tree structure [SELECTORS4][CSS21]. The Selectors API specification defines methods for retrieving Element nodes from the DOM by matching against a group of selectors, and for testing if a given element matches a particular selector. It is often desirable to perform DOM operations on a specific set of elements in a document. These methods simplify the process of acquiring and testing specific elements, especially compared with the more verbose techniques defined and used in the past.

Status of this Document

This section describes the status of this document at the time of its publication. Other documents may supersede this document. A list of current W3C publications and the latest revision of this technical report can be found in the W3C technical reports index at http://www.w3.org/TR/.

This is the 28 June 2012 Working Draft of "Selectors API". The W3C Membership and other interested parties are invited to review the document and send comments to public-webapps@w3.org (public archive) with [selectors-api] in the subject.

Implementors should be aware that this specification is not stable. Implementors who are not taking part in the discussions are likely to find the specification changing out from under them in incompatible ways. Vendors interested in implementing this specification before it eventually reaches the Candidate Recommendation stage should join the aforementioned mailing lists and take part in the discussions.

This document was developed by the Web Applications Working Group. The Working Group expects to advance this Working Draft to Recommendation Status.

Publication as a Working Draft does not imply endorsement by the W3C Membership. This is a draft document and may be updated, replaced or obsoleted by other documents at any time. It is inappropriate to cite this document as other than work in progress.

This document was produced by a group operating under the 5 February 2004 W3C Patent Policy. W3C maintains a public list of any patent disclosures made in connection with the deliverables of the group; that page also includes instructions for disclosing a patent. An individual who has actual knowledge of a patent which the individual believes contains Essential Claim(s) must disclose the information in accordance with section 6 of the W3C Patent Policy.

Table of Contents

1. Introduction

This section is non-normative.

This specification provides methods for selecting and testing elements based on whether or not they match a given selector. With these methods methods, it is easier to match a set of Element nodes based on specific criteria, than having to subsequently filter the result of calling other methods like getElementsByTagName().

1.1. Examples

This section is non-normative.

Some ECMAScript [ECMA-262] examples:

This is an example table written in HTML5.

<table id="score">
  <thead>
    <tr>
      <th>Test
      <th>Result
  <tfoot>
    <tr>
      <th>Average
      <td>82%
  <tbody>
    <tr>
      <td>A
      <td>87%
    <tr>
      <td>B
      <td>78%
    <tr>
      <td>C
      <td>81%
</table>

In order to obtain the cells containing the results in the table, which might be done, for example, to plot the values on a graph, there are at least two approaches that may be taken. Using only the APIs from DOM Level 2, it requires a script like the following that iterates through each tr within each tbody in the table to find the second cell of each row.

var table = document.getElementById("score");
var groups = table.tBodies;
var rows = null;
var cells = [];

for (var i = 0; i < groups.length; i++) {
  rows = groups[i].rows;
  for (var j = 0; j < rows.length; j++) {
    cells.push(rows[j].cells[1]);
  }
}

Alternatively, using the querySelectorAll() method, that script becomes much more concise.

var cells = document.querySelectorAll("#score>tbody>tr>td:nth-of-type(2)");

Note that the script operates on the DOM and works independently from the syntax used to create the document. Thus this script will also work correctly for an equivalent table created from well-formed XHTML instead of HTML, or dynamically created and inserted into a document using DOM APIs.

2. Conformance Requirements

All diagrams, examples and notes in this specification are non-normative, as are all sections explicitly marked non-normative. Everything else in this specification is normative.

The key words must, must not, should, may and recommended in the normative parts of this document are to be interpreted as described in RFC 2119 [RFC2119].

The following conformance classes are defined (and considered) by this specification:

conforming user agent
A user agent that implements the interfaces described in this specification and conforms to all must-level criteria that apply to implementations.
conforming application
An application that uses the interfaces defined in this specification and conforms to all must-level criteria that apply to applications.

2.1. Terminology and Conventions

The terminology used in this specification is that from Selectors [SELECTORS4].

The following features are defined in the DOM4 specification [DOM]:

Conformance requirements phrased as algorithms or specific steps may be implemented in any manner, so long as the end result is equivalent.

The IDL used in this specification uses the syntax defined in Web IDL [WEBIDL].

The construction "Foo object", where Foo is actually an interface, is sometimes used instead of the more accurate "object implementing the Foo interface".

3. Interoperability Considerations

This section is non-normative.

Some implementations might have different levels of support for Selectors. If some implementations lack support for some selectors, then the use of such selectors will result in those implementations failing to return the expected results. Authors are advised to check for the DOM Exceptions thrown by these APIs and provide a fallback for graceful degradation.

3.1. Extensibility

This section is non-normative.

Extensions of the APIs defined in this specification are strongly discouraged. Implementors, Working Groups and other interested parties should discuss extensions on a relevant public forum, such as public-webapps@w3.org.

4. Security Considerations

It is expected that implementing this specification introduces no new security risks for users.

If, at any time, the implementation detects a situation which would violate security policies, the implementation may abort and raise a security exception. If any other error condition occurs which is not covered directly by this or any other relevant specification, the implementation may abort and raise an appropriate, language-binding-specific or implementation-specific exception.

5. Privacy Considerations

History theft is a potential privacy issue because the :visited pseudo-class in Selectors [SELECTORS4] allows authors to query which links have been visited.

This is not a new problem, as it can already be exploited using existing CSS and DOM APIs, such as getComputedStyle() [DOM-LEVEL-2-STYLE].

In this example, vlinks will acquire a list of links that the user has visited. The author can then obtain the URIs and potentially exploit this knowledge.

var vlinks = document.querySelectorAll(":visited");
for (var i = 0; i < vlinks.length; i++) {
  doSomethingEvil(vlinks[i].href);
}

As defined in Selectors ([SELECTORS4], section 7.2), user agents may treat all links as unvisited links. It is recommended that implementations behave consistently with other uses of Selectors supported by the user agent.

6. The APIs

The term first used in the definitions of the methods defined in this specification means first in tree order. The term subtrees refers to the set of elements that are descendants of the specified context object. The term matching Element node refers to an Element node that matches the selector string (selectors) that was passed to the method, according to the rules for matching elements defined in Selectors [SELECTORS4].

6.1. Interface Definitions

partial interface Document {
  Element?  querySelector(DOMString selectors);
  NodeList  querySelectorAll(DOMString selectors);

  Element?  find(DOMString selectors, optional (Element or sequence<Node>)? refNodes);
  ?         findAll(DOMString selectors, optional (Element or sequence<Node>)? refNodes);
};

partial interface DocumentFragment {
  Element?  querySelector(DOMString selectors);
  NodeList  querySelectorAll(DOMString selectors);

  Element?  find(DOMString selectors, optional (Element or sequence<Node>)? refNodes);
  ?         findAll(DOMString selectors, optional (Element or sequence<Node>)? refNodes);
};

partial interface Element {
  Element?  querySelector(DOMString selectors);
  NodeList  querySelectorAll(DOMString selectors);

  Element?  find(DOMString selectors);
  ?         findAll(DOMString selectors);

  boolean   matches(DOMString selectors, optional (Element or sequence<Node>)? refNodes);
};

The names of the find/findAll methods are still not finalised. They are the names being used for the current discussion and may change.

The return type for findAll is undecided.

6.2. Finding Elements

The selectors argument for the querySelector and querySelectorAll methods accepts a selector string.

The selectors argument for the find and findAll methods accepts a relative selector string.

The optional refNodes argument specifies zero or more contextual reference element nodes.

The querySelector() methods on the Document, DocumentFragment, and Element interfaces must return the first matching Element node within the subtrees of the context object. If there is no matching Element, the method must return null.

The querySelectorAll() methods on the Document, DocumentFragment, and Element interfaces must return a NodeList containing all of the matching Element nodes within the subtrees of the context object, in tree order. If there are no matching nodes, the method must return an empty NodeList.

The find() methods on the Document, DocumentFragment, and Element interfaces must return the first matching Element node from the tree within which the context object is located. If there is no matching Element, the method must return null.

The findAll() methods on the Document, DocumentFragment, and Element interfaces must return a ? [collection] containing all of the matching Element nodes from the tree within which the context object is located. If there is no matching Element, the method must return an empty ? [collection].

When either method is invoked, the implementation must follow these steps:

  1. Let reference nodes be the result of running the algorithm to determine contextual reference nodes using refNodes as the input, if provided.

  2. Let parsed selector be the result of running the algorithm to parse a selector with selectors and reference nodes as the input.

  3. The implementation must then run the algorithm to evaluate a selector against element nodes in the specified tree or subtrees using parsed selector as the selector and reference nodes as the contextual reference element set, as needed to return the required result for the invoked method.

The NodeList returned by the querySelectorAll() method must be static ([DOM], section 8).

6.3. Matching Elements

The selectors argument for the matches method accepts a relative selector string.

The optional refNodes argument specifies zero or more contextual reference element nodes.

The matches() method on the Element interface must return true if the context object is a matching Element node. Otherwise, the method must return false.

When the method is invoked, the implementation must follow these steps:

  1. Let reference nodes be the result of running the algorithm to determine contextual reference nodes using refNodes as the input, if provided.

  2. Let parsed selector be the result of running the algorithm to parse a selector with selectors and reference nodes as the input.

  3. The implementation must then run the algorithm to evaluate a selector against the context object using parsed selector as the selector and reference nodes as the contextual reference element set.

6.4. Grammar

A selector string is a list of one or more complex selectors ([SELECTORS4], section 3.1) that may be surrounded by whitespace and matches the dom_selectors_group production.

A relative selector string is a list of one or more relative selectors that matches the dom_relative_selectors_group production.

A relative selector is a complex selector ([SELECTORS4], section 3.1) that may be preceded by a combinator, and matches the dom_relative_selector production.

dom_selectors_group
  : S* [ selectors_group ] S*
  ;

dom_relative_selectors_group
  : [ dom_relative_selector [ COMMA S* dom_relative_selector ]* ] S*
  ;

dom_relative_selector
  : [ combinator ]? selector
  ;

The productions for selectors_group, combinator and selector are defined in Selectors 4 ([SELECTORS4], section 16.1). These groups of selectors should not use namespace prefixes that need to be resolved.

Fix references

Implementers are advised that if null or undefined are passed as the value of the selectors parameter, they are to be handled as defined in WebIDL [WEBIDL]. Authors are advised to avoid passing these values.

Authors are advised that while the use of pseudo-elements in selectors is permitted, they will not match any elements in the document, and thus would not result in any elements being returned. Therefore, authors are advised to avoid the use of pseudo-elements in selectors that are passed to the methods defined in this specification.

6.5. Processing Selectors

The steps to parse a selector are as follows:

  1. Let selectors be the selector string or relative selector string input to this algorithm.

  2. Let reference nodes be the reference nodes input to this algorithm.

  3. If selectors is a selector string, then:

    1. If selector string matches the grammar for dom_selectors_group, let result be the group of selectors returned as a result of parsing the selectors according to the grammar for dom_relative_selectors_group defined above.

    2. Otherwise, throw a SyntaxError exception ([DOM], section 3.1) and abort this algorithm.

  4. Otherwise, if selectors is a relative selector string, then:

    1. If selector string matches the grammar for dom_relative_selectors_group, let selectors group be the group of selectors returned as a result of parsing the selectors according to the grammar for dom_relative_selectors_group defined above.

    2. Otherwise, throw a SyntaxError exception ([DOM], section 3.1) and abort this algorithm.

    3. Let result be an initially empty group of selectors.

    4. For each relative selector in selectors group:

      1. If the relative selector begins with a combinator and that combinator is not ' ' (space), then prepend the simple selector ":scope" to the relative selector.

      2. Otherwise, if the reference nodes is an empty collection, do nothing.

      3. Otherwise, if any compound selector within relative selector includes a functional pseudo-class that accepts a selector as its parameter, and which contains the ":scope" pseudo-class anywhere within it, then do nothing.

      4. Otherwise, if the relative selector includes :scope within any compound or simple selector, then do nothing.

      5. Otherwise, prepend the simple selector ":scope" and a descendant combinator (' ') to the relative selector.

      6. Add relative selector to result.

  5. Return result.

The steps to evaluate a selector are as follows:

  1. Let element be the element being evaluated.

  2. Let selector group be the selector input into this algotihm.

  3. Let reference nodes be the reference nodes input into this algorithm.

  4. For the purpose of evaluating the :scope pseudo-class, the contextual reference element set contains all Element nodes contained within reference nodes.

  5. If any selector in selector group matches element, return true. Otherwise, return false.

Selectors are evaluated against a given element in the context of the entire DOM tree in which the element is located.

If the user agent also supports some level of CSS, the implementation should support the same set of selectors in both these APIs and CSS.

6.6. Processing Reference Nodes

The steps to determine contextual reference nodes are as follows:

  1. Let input be the value that is being processed, if provided.

  2. Let result be an initially empty collection of Element nodes.

  3. If the input was provided, then:

    1. If input is an Element node, then append that Element to the result collection.

    2. If input is a sequence of Node objects, then iterate through the sequence and append each Element node contained within it to the result collection.

    3. If input is null, then do nothing.

      This leaves the result collection empty.

  4. Otherwise, if input was omitted, then:

    1. If the context object is an Element node, then append that Element to the result collection.

  5. Return result.

The result may still be an empty collection at the end of that process.

If the refNodes parameter was passed a sequence containing objects other than Node objects, then a TypeError will be thrown ([WEBIDL]).

6.7. Resolving Namespaces

If the group of selectors include namespace prefixes that need to be resolved, the implementation must throw a SyntaxError exception ([DOM], section 3.1).

This specification does not provide support for resolving arbitrary namespace prefixes. However, support for a namespace prefix resolution mechanism may be considered for inclusion in a future version of this specification.

A namespace prefix needs to be resolved if the namespace component is neither empty (e.g. |div), representing the null namespace, or an asterisk (e.g. *|div), representing any namespace. Since the asterisk or empty namespace prefix do not need to be resolved, implementations that support the namespace syntax in Selectors must support these. [SELECTORS4]

7. The :scope Pseudo-Class

This section is expected to be moved to the Selectors Level 4 specification when the CSSWG begins work. It is defined here only because it needs to be defined somewhere. Note that this has been called various names including :reference and :context in previous discussions.

A contextual reference element is a specified reference Element node within the context in which a selector is being evaluated. The contextual reference element set is a collection of all contextual reference element nodes. There may be zero or more such elements in a given context.

If the contextual reference element set is not specified for a given context and the element being evaluated has an ownerDocument, the documentElement of the ownerDocument is in the contextual reference element set. Otherwise, the contextual reference element set is empty.

The :scope pseudo-class must match any element that is in the contextual reference element set.

Specifications intending for this pseudo-class to match specific elements other than the document's root element must define a contextual reference element set.

8. DOM Feature String

DOM3 Core defines several methods for checking for interface support, or for obtaining implementations of interfaces, using feature strings ([DOM-LEVEL-3-CORE], section 1.3.6). A DOM application can use these methods, each of which accept feature and version parameters, using the values "Selectors-API" and "1.0" (respectively).

The version parameter has been intentionally left as "1.0". This is intended only as a way to detect the presence of some level of support, rather than being able claim support for a specific level of this API.

Conforming implementations must respond with a true value when the hasFeature method is queried with these values. Authors are cautioned, however, that implementations returning true might not be perfectly compliant, and that implementations returning false might well have support for features in this specification; in general, therefore, use of this method is discouraged.

9. Examples

Add more examples illustrating the use of the reference node and :scope selector, as well as the find() and matches() methods.

The following examples make use of this sample XHTML document.

<html xmlns="http://www.w3.org/1999/xhtml">
  <head>
    <title>Selectors API Example</title>
  </head>
  <body>
    <div id="foo">
      <p class="warning">This is a sample warning</p>
      <p class="error">This is a sample error</p>
    </div>
    <div id="bar">
      <p>...</p>
    </div>
  </body>
</html>

The methods accept a group of selectors (comma separated) as the argument. The following example would select all p elements in the document that have a class of either "error" or "warning".

var alerts = document.querySelectorAll("p.warning, p.error");

The querySelector() methods also accept a group of selectors and they will return the first element (if any) that matches any of the selectors in the group.

var x = document.querySelector("#foo, #bar");

x would contain the first element in the document with an ID of either foo or bar, or null if there is no such element. In the sample document above, it would select the div element with the ID of foo because it is first in tree order. The order of the selectors used in the parameter has no effect and would have the same result if the order were reversed, as in:

var x = document.querySelector("#bar, #foo");

The methods can also be invoked on elements. In the following example, assume the event handler is registered on an element, and thus the method is invoked on the target element of the event.

function handle(evt) {
  var x = evt.target.querySelector("span");
  ...
  // Do something with x
}

Even though the method is invoked on an element, selectors are still evaluated in the context of the entire document. In the following example, the method will still match the div element's child p element, even though the body element is not a descendant of the div element itself.

var div = document.getElementById("bar");
var p = div.querySelector("body p");

Given this sample fragment that contains a list as a navigation menu:

<ul class="nav">
  <li><a href="/">Home</a></li>
  <li><a href="/products">Products</a></li>
  <li><a href="/about">About</a></li>
</ul>

The following example selects all the li elements and demonstrates how to iterate through the collection in a NodeList.

var lis = document.querySelectorAll("ul.nav>li");
for (var i = 0; i < lis.length; i++) {
  process(lis.item(i));
}

In ECMAScript, the language binding also allows NodeLists to be addressed using the array notation, so that loop could be rewritten like this:

for (var i = 0; i < lis.length; i++) {
  process(lis[i]);
}

Since the NodeList objects returned by these methods are not live, changes to the DOM do not affect the content of the list. Consider the process() function called in the previous examples is defined as follows:

function process(elmt) {
  elmt.parentNode.removeChild(elmt);
}

This would cause each selected element to be removed from the DOM, but each element will remain in the NodeList. If the list were a live NodeList, removing an item from the DOM would also remove the element from the list and adjust the indexes of subsequent elements. That would have adverse effects upon the loop because not all selected elements would be processed.

In documents comprising elements from multiple namespaces, it's possible that some elements from different namespaces share the same local name. Since this API does not natively support a namespace resolution mechanism for selectors, obtaining a list of such elements from a specific namespace, excluding all others, requires additional processing to filter the result. The following example illustrates a document containing video elements from both the SVG and XHTML namespaces.

<svg id="svg1" xmlns="http://www.w3.org/2000/svg"
               xmlns:xlink="http://www.w3.org/1999/xlink">
  <video id="svgvideo1" xlink:href="myvideo.ogg" width="320" height="240"/>
  <foreignObject width="100" height="100">
    <video id="htmlvideo1" src="myvideo.ogg" xmlns="http://www.w3.org/1999/xhtml">No video1</video>
  </foreignObject>
</svg>

The following script demonstrates how to first select the video elements and then filter out the unwanted elements based on their namespace.

var elms = document.querySelectorAll("svg video");
var result = new Array();
var svgns = "http://www.w3.org/2000/svg"

for(var i = 0; i < elms.length; i++) {
  if(elms[i].namespaceURI == svgns) {
    result.push(elms[i]);
  }
}

References

Normative references

[DOM]
Anne van Kesteren; Aryeh Gregor; Ms2ger. DOM4. 5 April 2012. W3C Working Draft. (Work in progress.) URL: http://www.w3.org/TR/2012/WD-dom-20120405/
[DOM-LEVEL-3-CORE]
Gavin Nicol; et al. Document Object Model (DOM) Level 3 Core Specification. 7 April 2004. W3C Recommendation. URL: http://www.w3.org/TR/2004/REC-DOM-Level-3-Core-20040407
[RFC2119]
S. Bradner. Key words for use in RFCs to Indicate Requirement Levels. Internet RFC 2119. URL: http://www.ietf.org/rfc/rfc2119.txt
[SELECTORS4]
Elika J. Etemad. Selectors Level 4. 29 September 2011. W3C Working Draft. (Work in progress.) URL: http://www.w3.org/TR/2011/WD-selectors4-20110929/
[WEBIDL]
Cameron McCormack. Web IDL. 19 December 2008. W3C Working Draft. (Work in progress.) URL: http://www.w3.org/TR/2008/WD-WebIDL-20081219

Informative references

[CSS21]
Bert Bos; et al. Cascading Style Sheets Level 2 Revision 1 (CSS 2.1) Specification. 7 June 2011. W3C Recommendation. URL: http://www.w3.org/TR/2011/REC-CSS2-20110607
[DOM-LEVEL-2-STYLE]
Chris Wilson; Philippe Le Hégaret; Vidur Apparao. Document Object Model (DOM) Level 2 Style Specification. 13 November 2000. W3C Recommendation. URL: http://www.w3.org/TR/2000/REC-DOM-Level-2-Style-20001113
[ECMA-262]
ECMAScript Language Specification, Third Edition. December 1999. URL: http://www.ecma-international.org/publications/standards/Ecma-262.htm

Acknowledgements

The editors would like to thank to the following people who have contributed to this specification (ordered on first name):

Adam van den Hoven, Alan Gresley, Alex Russell, Björn Höhrmann, Boris Zbarsky, Cameron McCormack, Charles McCathieNevile, Chris Wilson, Christophe Jolif, Daniel Glazman, Daniel Schierbeck, Dave Massy, David "liorean" Andersson, David Håsäther, Dean Jackson, Doug Schepers, Erik Dahlström, Francois Remy, Hallvord R. M. Steen, Ian Hickson, Ivan Enderlin, Jean-Yves Bitterlich, Jim Ley, João Eiras, John Resig, Jon Ferraiolo, Jonas Sicking, Jorgen Horstink, Karl Dubost, Kartikaya Gupta, L. David Baron, Maciej Stachowiak, Magnus Kristiansen, Martijn, Masataka Yakura, Mihai Sucan, Mohamed Zergaoui, Nicholas C. Zakas, Nicolas Mendoza, Philip Taylor, Robert Sayre, Robin Berjon, Sander, Sergey Ilinsky, Simon Pieters, Steven Pemberton, Tarquin Wilton-Jones, Travis Leithead, and William J. Edney

Special thanks to Anne van Kesteren, the original editor of Selectors API Level 1.

Thanks to all those who have helped to improve this specification by sending suggestions and corrections.