Copyright © 2006-2007 W3C® (MIT, ERCIM, Keio), All Rights Reserved. W3C liability, trademark and document use rules apply.
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, 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.
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 19 January First Public Working Draft of "Selectors API Level 2". 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.
The editor’s copy of this specification is available in W3C CVS. A detailed list of changes is also available from the CVS server.
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.
:scope
Pseudo-Class
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()
.
This section is non-normative.
Some ECMAScript [ECMA-262] 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)");
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.
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:
NodeSelector
interface described in
this specification and conforms to all must-level
criteria that apply to implementations.
The terminology used in this specification is that from Selectors [SELECT].
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".
The interfaces used within, but not defined by, this specification,
including Document
, DocumentFragment
,
Node
and Element
are
defined in DOM Level 3 Core [DOM-LEVEL-3-CORE].
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.
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.
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.
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.
The term first used in the definitions of the
methods defined in this specification 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 subtrees
refers to the collection of elements that are descendants of the specified
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].
NodeSelector
Interfacemodule dom { [Supplemental, NoInterfaceObject] interface NodeSelector { Element querySelector(in DOMString selectors, in optional any refNodes); NodeList querySelectorAll(in DOMString selectors, in optional any refNodes); Element queryScopedSelector(in DOMString selectors); NodeList queryScopedSelectorAll(in DOMString selectors); }; Document implements NodeSelector; DocumentFragment implements NodeSelector; Element implements NodeSelector; };
The selectors argument for the querySelector
and querySelectorAll
method accepts a selector string.
The selectors argument for the queryScopedSelector
and queryScopedSelectorAll
methods
accepts a scoped selector string.
The optional refNodes argument specifies one or more contextual reference element nodes.
When either method is invoked, the implementation must follow these steps.
If the selectors argument is a selector string, let parsed selector be the result of running the algorithm to parse a selector with selectors as the input.
If the selectors argument is a scoped selector string, let parsed selector be the result of running the algorithm to parse a scoped selector using selectors as the input.
Let reference nodes be the result of running the algorithm to determine contextual reference nodes using refNodes as the input, if provided.
The implementation must then run the algorithm to evaluate a selector against element nodes in the tree using parsed selector as the selector and reference nodes as the contextual reference element nodes, as needed to return the required result for invoked method.
The querySelector()
method on the
NodeSelector
interface must return the first matching Element
node within the subtrees of the context
node. If there is no such node, the method must
return null
.
The querySelectorAll()
method on the
NodeSelector
interface must return a NodeList
containing all of the
matching Element
nodes within the
subtrees of the context
node, in document order. If there are no
such nodes, the method must return an empty
NodeList
.
The queryScopedSelector()
method
on the NodeSelector
interface must, when invoked, return the first matching Element
node within the entire DOM tree in
which the context node is located. If there is
no such node, the method must return null
.
The queryScopedSelectorAll()
method on the NodeSelector
interface must return a NodeList
containing
all of the matching Element
nodes
within the entire DOM tree in which the context
node is located, in document order. If
there are no such nodes, the method must return an empty
NodeList
.
The NodeList
object returned by the querySelectorAll()
and queryScopedSelectorAll()
methods
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.
module dom { [Supplemental] interface Element { boolean matchesSelector(in DOMString selectors, in optional any refNodes]); }; };
The selectors argument accepts a selector string.
The optional refNodes argument specifies one or more contextual reference element nodes.
When the method is invoked, the implementation must follow these steps.
Let parsed selector be the result of running the algorithm to parse a selector with selectors as the input.
Let reference nodes be the result of running the algorithm to determine contextual reference nodes using refNodes as the input, if provided.
The implementation must then run the algorithm to evaluate a selector against the context node using parsed selector as the selector and reference nodes as the contextual reference element nodes.
The matchesSelector()
method on the
Element
interface must, when invoked, return true if the context node is a matching Element
node.
Otherwise, the method must return false.
A selector string is a group of
selectors ([SELECT], section 5). This group of
selectors should match the selectors_group
production ([SELECT], section 10) with the
additional provision that leading and trailing whitespace ([SELECT], section 4) is permitted.
This group of selectors should not use namespace prefixes that need to be resolved.
A scoped selector string is a group of
selectors ([SELECT], section 5), that will
imply the presence of the :scope
pseudo-class at the beginning, if not specified explicilty.
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.
The steps to parse a selector are as follows:
The steps for parse a scoped selector are as follows:
:scope
pseudo-class, insert the simple selector
:scope
followed by a descendant
combinator at the beginning.
For example, if the scoped selector
string is “div div, :scope+p"
” the processing will
result in the selector being equivalent to “:scope div div,
:scope+p
”
The steps to evaluate a selector are as follows:
:scope
pseudo class, if used in
selector group, must match any node within the reference
nodes collection.
Selectors are evaluated against a given element in the context of 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 steps to determine contextual reference nodes are as follows:
Element
nodes.
Element
node, then that append that
element to the result collection.
NodeList
or
HTMLCollection
, then append each Element
node contained within it to the
result collection.
Array
or other object with
indexable properties, then iterate through input to find and
append each Element
node
contained within it to the result collection.
Element
node, append the context node to the result
collection.
Document
node,
then append the documentElement
of the given document, if
any, to the result collection.
The result may still be an empty collection at the end of that process.
If the group of selectors include namespace prefixes that need to be resolved, the
implementation must raise
a NAMESPACE_ERR
exception ([DOM-LEVEL-3-CORE],
section 1.4).
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. [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.
In addition to the terms defined in this specification, the terms defined in Selectors [SELECT] and DOM Level 3 Core [DOM-LEVEL-3-CORE] are also used.
:scope
Pseudo-ClassThis 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. There may be more than one such element in a
given context.
The :scope
pseudo-class must match any element that is a contextual reference element.
When a given element is being evaluated against a given selector in a given context, there may be one or more contextual reference element nodes specified. If there are no other contextual reference element nodes specified, and the element being evaluated belongs to a document, the root element of the document to which the element belongs is a contextual reference element. Otherwise, there is no contextual reference element.
Specifications intending for this pseudo-class to match specific elements other than the document's root element must define which elements are the contextual reference element nodes.
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.
Add more examples illustrating the use of the reference node and :scope selector, as well as the queryScopedSelector() and matchesSelector() 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 document 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 NodeList
s
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 list = 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(list[i].namespaceURI == svgns) { result.push(elms[i]); } }
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, Garret Smith, 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
Thanks to all those who have helped to improve this specification by sending suggestions and corrections.