Selectors API

Selectors, which are widely used in CSS, are patterns that match against elements in a tree structure [SELECT][CSS21]. The Selectors API specification defines methods for retrieving Element nodes from the DOM by matching against a group of selectors. It is often desirable to perform DOM operations on a specific set of elements in a document. These methods simplify the process of acquiring 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 a Last Call 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, through 12 December 2008.

Web content and browser developers are encouraged to review this draft. This draft is considered relatively stable and is expected to progress to Candidate Recommendation after the review period. The editor’s copy of this specification is available in W3C CVS. A detailed list of changes is also available from the CVS server.

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.

1. Introduction

This specification introduces two methods that take a group of selectors (often simply referred to as a selector) as an argument and return the matching elements [SELECT]. With these methods, it is easier to match a set of Element nodes based on specific criteria. So instead of having to filter the result of a getElementsByTagName() call, authors can directly “filter” in the query.

1.1 Examples

This is an example table written in HTML 4.01.

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

This script will also function correctly for a table written in XHTML markup instead of HTML.

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:

2.1 Terminology and Conventions

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

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

Some implementations might have different levels of support for Selectors. If some implementations lack support for some selectors, then if those selectors are used, such implementations could return different results from those that do support them.

3.1 Extensibility

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 [SELECT] 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 ([SELECT], section 6.6.1), 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 NodeSelector Interface

Objects implementing any of the Document, DocumentFragment or Element interfaces, as defined in DOM Level 3 Core, must also implement the NodeSelector interface. [DOM-LEVEL-3-CORE]

The term first used in the definitions of the querySelector methods means first in document order. The term document order means a depth-first pre-order traversal of the DOM tree or subtree in question. The term context node refers to the node upon which the method was invoked. The term node’s subtree refers to the tree of elements that are descendants of the context node. The term matching Element node refers to an Element node that matches the group of selectors (selectors) that was passed to the method, according to the rules for matching elements defined in Selectors [SELECT].

The querySelector() method on the NodeSelector interface must, when invoked, return the first matching Element node within the node’s subtree. If there is no such node, the method must return null.

The querySelectorAll() method on the NodeSelector interface must, when invoked, return a NodeList containing all of the matching Element nodes within the node’s subtree, in document order. If there are no such nodes, the method must return an empty NodeList.

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.

The implementation must first trim any leading or trailing whitespace from the value of the selectors parameter. The implementation must then process the value according to the grammar of Selectors ([SELECT], section 10). If the selectors parameter is set to either null or undefined, the implementation must behave as if an empty string had been passed instead. Selectors are evaluated against a given element in the context the entire DOM tree in which the element is located. If the given group of selectors is invalid ([SELECT], section 13), the implementation must raise a SYNTAX_ERR exception ([DOM-LEVEL-3-CORE], section 1.4).

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.

The NodeList object returned by the querySelectorAll() method must be static, not live. ([DOM-LEVEL-3-CORE], section 1.1.1) Subsequent changes to the structure of the underlying document must not be reflected in the NodeList object. This means that the object will instead contain a list of matching Element nodes that were in the document at the time the list was created.

6.1 Resolving Namespaces

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. [SELECT]

Implementations that don't support the namespace syntax in Selectors would instead throw a SYNTAX_ERR because it would be treated as an invalid selector.

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

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.

8. Examples

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 both). In the sample document above, it would select the div element with the ID of foo because it is first in document order.

The methods can also be invoked on elements. In this 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 = bar.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 and 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.

References

Normative references

Other references

Acknowledgements

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

Thanks to all those who have helped to improve this specification by sending suggestions and corrections. (Please, keep bugging us with your issues!)

Selectors API

W3C Working Draft 14 November 2008

Abstract

Status of this Document

Table of Contents

1. Introduction

1.1 Examples

2. Conformance Requirements

2.1 Terminology and Conventions

3. Interoperability Considerations

3.1 Extensibility

4. Security Considerations

5. Privacy Considerations

6. The `NodeSelector` Interface

6.1 Resolving Namespaces

7. DOM Feature String

8. Examples

References

Normative references

Other references

Acknowledgements

Selectors API

W3C Working Draft 14 November 2008

Abstract

Status of this Document

Table of Contents

1. Introduction

1.1 Examples

2. Conformance Requirements

2.1 Terminology and Conventions

3. Interoperability Considerations

3.1 Extensibility

4. Security Considerations

5. Privacy Considerations

6. The NodeSelector Interface

6.1 Resolving Namespaces

7. DOM Feature String

8. Examples

References

Normative references

Other references

Acknowledgements

6. The `NodeSelector` Interface