Selectors API

W3C Working Draft 25 May 2006

This version:
Latest version:
Anne van Kesteren (Opera Software ASA) <annevk@opera.com>


This specification defines two methods for retrieving Element nodes in the DOM using a group of selectors as defined in [Selectors].

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 25 May 2006 Working Draft of the Selectors API, the first publication of this specification. This document is produced by the Web API WG, part of the Rich Web Clients Activity in the W3C Interaction Domain. The authors of this document are the members of the W3C Web API Working Group.

Web content and browser developers are encouraged to review this draft. Please send comments to public-webapi@w3.org, the W3C's public email list for issues related to Web APIs. Archives of the list are available.

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.

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.

Table of Contents

  1. Introduction
    1. Examples
    2. Conformance Requirements
    3. Outstanding Issues
  2. Interfaces
    1. The DocumentSelector Interface
      1. Extensibility
    2. The StaticNodeList Interface
  3. Security Considerations
  1. References
  2. Acknowledgements


This section is non-normative.

It is often desirable to perform script and or DOM operations on a specific set of elements in a document. [Selectors], mostly used in CSS [CSS21] context, provides a way of matching such a set of elements. This specification introduces two methods which take a selector (technically a group of selectors) as argument and return the matched elements as result.


This section is non-normative.

Some ECMAScript [ECMA262] examples:

function resolver(str) {
  var prefixes = {
    xh:  "http://www.w3.org/1999/xhtml",
    svg: "http://www.w3.org/2000/svg"}
  return prefixes[str];
var a = document.matchAll("xh|div > svg|svg", resolver);
var b = document.match("div.foo.bar");

a contains a StaticNodeList of all the nodes matched by xh|div > svg|svg (namespace prefixes are resolved using the function in this case). b would contain the first div element which has the classes foo and bar set. (So in case of multiple div elements matching div.foo.bar only the first is returned because match is used and not matchAll.)

function test(){
  var c = document.matchAll(":root"),
      d = document.documentElement;
  return c[0] === d;

test() would return true when both matchAll and :root are supported.

When using :root like this it's probably better (and faster) to use match given that there's only one possible result. This is just to illustrate how it works.

var e = document.matchAll("p.warning, p.alert");

The above code snippet shows that besides using a single selector you can also pass a group of selectors (basically comma-separated selectors) as argument. e would contain a StaticNodeList with all p elements in the document that have a warning or alert class.

Conformance Requirements

Everying in this specification is normative except for diagrams, examples, notes and sections marked non-normative.

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

conforming implementation
A UA that implements all interfaces described in this specification and follows all must-, required- and shall-level of critera in this specification.
conforming document
A document that follows all must-, required- and shall-level of critera in this specification that apply to document authors.
conforming authoring tool
One that produces conforming documents.

Outstanding Issues

This section is non-normative.

The draft has several outstanding issues that either need to be addressed in one way or another at some point:


The DocumentSelector Interface

Objects implementing the Document interface defined in DOM Level 3 Core must also implement the DocumentSelector interface [DOM3Core].

interface DocumentSelector {
  Node            match(in DOMString selectors, in XPathNSResolver nsresolver);
  StaticNodeList  matchAll(in DOMString selectors, in XPathNSResolver nsresolver);

The match method, when invoked, must return the first (using depth-first pre-order traversal) Element that matches the group of selectors (selectors), if any. Otherwise it must return null.

The matchAll method, when invoked, must return a StaticNodeList of all the Elements that match the group of selectors (selectors) in document order (using depth-first pre-order traversal), if any. Otherwise it must return null.

Both match and matchAll take a group of selectors (selectors) as defined in [Selectors] as first argument and an XPathNSResolver (nsresolver) as second. UAs must use the nsresolver argument to resolve namespace prefixes as defined in [DOM3XPath]. When the nsresolver argument is null UAs must ignore it.

When authors use namespace prefixes within selectors they must create an object implementing the XPathNSResolver interface (or may create a Function in case of ECMAScript) and pass that as argument for nsresolver as defined in in [DOM3XPath]. If they don't use namespace prefixes within selectors authors may set nsresolver to null or omit the argument completely if the language binding allows it.

Make sure [DOM3XPath] actually defines this. Otherwise this draft will have to. (Which is needed anyway when this goes beyond Last Call and DOM Level 3 XPath does not.)

If the given group of selectors (selectors) is invalid, the UA must raise a SYNTAX_ERR exception. If the given group of selectors (selectors) uses namespace prefixes and the prefix can not be resolved using the nsresolver argument UAs must raise a NAMESPACE_ERR exception.

Using psuedo-elements in one of the selectors could mean that nothing is returned for that particular selector when it doesn't resolve in one or more Element nodes.

In languages that support optional arguments for methods, like ECMAScript, omitting the nsresolver argument in either the match or matchAll method must return the same result as if the method was called with the nsresolver argument being null.


Extensions to the DocumentSelector interface are reserved for future work by the Web APIs WG. WGs besides the Web APIs WG may extend the interface, but must coordinate that with the Web APIs WG. UAs may extend the interface, but must prefix the new members using a string specific to the vendor following the VendorMember scheme. (Normally members follow the member scheme.) FooSetDefaultNamespace(ns) would be an example for company Foo.

Authors may use extension mechanisms specific to the host language, like .prototype in ECMAScript.

The StaticNodeList Interface

typedef StaticNodeList NodeList;

The StaticNodeList must be implemented identically to the NodeList interface as defined in [DOM3Core] with the exception that the interface, as the name suggests, is static and not live.

Security Considerations

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

History theft is a potential security problem, because of the :visited pseudo-class in [Selectors]. :visited can already be used to query which links are visited and which are not using methods from [DOM2Style] and even [CSS21] and because this specification did not introduce the problem and it can already be exploited by other means UAs don't have to take action upon it.

Another problem is hostile content. UAs should ensure they remain stable when facing a hostile XPathNSResolver object. Potential hostile things such an object could do include:

It was said that this section is in need of examples...


(Informative) Cascading Style Sheets, level 2 revision 1, B. Bos, T. Çelik, I. Hickson, H. Wium Lie, editors. World Wide Web Consortium, June 2005.
(Informative) Document Object Model (DOM) Level 2 Style Specification, C. Wilson, P. Le Hégaret, V. Apparao, editors. World Wide Web Consortium, November 2000.
Document Object Model (DOM) Level 3 Core Specification, A. Le Hors, P. Le Hégaret, L. Wood, G. Nicol, J. Robie, M. Champion, S. Byrne, editors. World Wide Web Consortium, April 2004.
Document Object Model (DOM) Level 3 XPath Specification, R. Whitmer, editor. World Wide Web Consortium, February 2004.
ECMAScript Language Specification, Third Edition. ECMA, December 1999.
Selectors, D. Glazman, T. Çelik, I. Hickson, P. Linss, J. Williams, editors. World Wide Web Consortium, December 2005.
RFC 2119: Key words for use in RFCs to Indicate Requirement Levels, S. Bradner. IETF, March 1997.


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