Note: This documentation is preliminary and is subject to change.
The Selector API lets you use Cascading Style Sheets (CSS) selectors to select objects with JavaScript. This article describes the Selector API and how use it to select objects with Javascript.
Introduction
When used with CSS, selectors provide a convenient way to select groups of objects. As of Internet Explorer 8, you can now use selectors to select groups of objects using Javascript. This article describes Internet Explorer's support for the W3C Selectors API 
, and shows how you can use it to select objects in your Javascript applications.
Note: The Selector API is only available to documents that opt into IE8 Mode; for more information, please see Defining Document Compatibility.
The Selector API provides two methods that allow you to use selectors to select objects. The querySelector method selects the first object that matches your criteria,
and the querySelectorAll method returns a collection of all objects that match your criteria. You can select objects from the document objects, or objects that descend from a common container object.
Limiting the Scope of Selector Queries
By default, Selector API queries include all objects in the document. For example, the following code returns a list of DIV elements that share the same class value.
<html>
<head>
<!-- Set document compatibility mode to IE8Mode. -->
<meta http-equiv="X-UA-Compatible" content="IE=8">
</head>
<body>
<script language="Javascript">
function doit()
{
var oAllPs = document.querySelectorAll("div.detail");
var sFound = ( oAllPs == null ) ?
"No matches found" : allPs.length;
alert( "Results: " + sFound );
}
</script>
<button >Simple Selector Example</button>
<ul>
<li><div class="header" name="first">Alpha</div></li>
<ol>
<li><div class="detail">One</div></li>
<li><div class="detail">Two</div></li>
<li><div class="detail">Three</div></li>
</ol>
<li><div class="header" name="second">Beta</div></li>
<ol>
<li><div class="detail">Four</div></li>
<li><div class="detail">Five</div></li>
<li><div class="detail">Six</div></li>
</ol>
<li><div class="header" name="third" >Gamma</div></li>
<ol>
<li><div class="detail">Seven</div></li>
<li><div class="detail">Eight</div></li>
<li><div class="detail">Nine</div></li>
</ol>
</ul>
</body>
</html>You can limit the scope of Selector API queries to the child object of a given container object. When you do this, your query only returns objects contained by the limiting object; these results do not contain the limiting object itself.
The following code sample is similar to the previous one; however, it limits the query to the second header div element.
<html>
<head>
<!-- Set document compatibility mode to IE8Mode. -->
<meta http-equiv="X-UA-Compatible" content="IE=8">
</head>
<body>
<script language="Javascript">
function doit()
{
var oLimit = document.querySelector("#second");
var oAllPs = oLimit.querySelectorAll("div");
var sFound = ( oAllPs == null ) ?
"No matches found" : oAllPs.length;
alert( "Results: " + sFound );
}
</script>
<button >Simple Selector Example</button>
<ul>
<li><div class="header" id="first">Alpha</div></li>
<ol>
<li><div class="detail">One</div></li>
<li><div class="detail">Two</div></li>
<li><div class="detail">Three</div></li>
</ol>
<li><div class="header" id="second">Beta</div></li>
<ol>
<li><div class="detail">Four</div></li>
<li><div class="detail">Five</div></li>
<li><div class="detail">Six</div></li>
</ol>
<li><div class="header" id="third" >Gamma</div></li>
<ol>
<li><div class="detail">Seven</div></li>
<li><div class="detail">Eight</div></li>
<li><div class="detail">Nine</div></li>
</ol>
</ul>
</body>
</html>When you limit queries to specific elements, you are only limiting the results of the query. Your query criteria can refer to objects outside the containership of the limiting element. To illustrate, consider the following sample.
<html>
<head>
<meta http-quiv="X-UA-Compatible" content="IE=8">
<title>Limit Example 1</title>
<head>
<body>
<p>
<div name="div1"><span name="span1">Found</span></div>
<div name="div2"><span name="span2">Not found</span></div>
</p>
<script>
function Sample()
{
var oDiv = document.getElementByName( "div1" );
var oSpan = oDiv.querySelector( "p span" );
var sResult = ( oSpan == null ) ?
"No match found; check your query" : "The query returned " + oSpan.name;
alert( sResult );
}
</script>
<button >Run Test</button>
</body>
</html>Notice that this sample contains a P element that contains two DIV elements. Each DIV element contains a single SPAN element.
Note When you run this sample in Internet Explorer 8, it returns the first SPAN element. Because the query is limited to the first DIV element, the results include only the first SPAN element, even though the criteria refers to the P element containing both DIV elements.
Specifying Multiple Selector Rules
You can specify multiple selector rules in a selector query. To do so, separate each rule with commas. The following sample specifies a query that selects div and span elements.
<html>
<head>
<!-- Set document compatibility mode to IE8Mode. -->
<meta http-equiv="X-UA-Compatible" content="IE=8">
</head>
<body>
<script language="Javascript">
function doit()
{
var oAllPs = document.querySelectorAll("div, span");
var sFound = ( oAllPs == null ) ?
"No matches found" : oAllPs.length;
alert( "Results: " + sFound );
}
</script>
<button >Simple Selector Example</button>
<ul>
<li><span class="header" id="first">Alpha</span></li>
<ol>
<li><div class="detail">One</div></li>
<li><div class="detail">Two</div></li>
<li><div class="detail">Three</div></li>
</ol>
<li><span class="header" id="second">Beta</span></li>
<ol>
<li><div class="detail">Four</div></li>
<li><div class="detail">Five</div></li>
<li><div class="detail">Six</div></li>
</ol>
<li><span class="header" id="third" >Gamma</span></li>
<ol>
<li><div class="detail">Seven</div></li>
<li><div class="detail">Eight</div></li>
<li><div class="detail">Nine</div></li>
</ol>
</ul>
</body>
</html>
Important For security reasons, Internet Explorer 8 ignores the
:visited and
:link pseudo class selectors when they appear in selector query criteria. If a selector query combines either pseudo class with other rules, the other rules are processed as usual.
NameSpace Support
Because Internet Explorer 8 does not formally support XHTML documents, it does not support the namespace features of the W3C Selectors API specification, such as the NSResolver parameter.