Selectors Level 4

Group: CSSWG
Shortname: selectors
Level: 4
Status: ED
Work Status: Revising
ED: https://drafts.csswg.org/selectors
TR: https://www.w3.org/TR/selectors4/
Previous Version: https://www.w3.org/TR/2013/WD-selectors4-20130502/
Previous Version: https://www.w3.org/TR/2012/WD-selectors4-20120823/
Previous Version: https://www.w3.org/TR/2011/WD-selectors4-20110929/
Editor: Elika J. Etemad / fantasai, Invited Expert, http://fantasai.inkedblade.net/contact
Editor: Tab Atkins Jr., Google, http://xanthir.com/contact/
Former Editor: Tantek Çelik, http://www.tantek.com
Former Editor: Daniel Glazman
Former Editor: Ian Hickson
Former Editor: Peter Linss
Former Editor: John Williams
Abstract: Selectors are patterns that match against elements in a tree, and as such form one of several technologies that can be used to select nodes in a document. Selectors have been optimized for use with HTML and XML, and are designed to be usable in performance-critical code. They are a core component of CSS (Cascading Style Sheets), which uses Selectors to bind style properties to elements in the document.
Abstract: Selectors Level 4 describes the selectors that already exist in [[!SELECT]], and further introduces new selectors for CSS and other languages that may need them.
At Risk: the column combinator
At Risk: the '':drop()'' pseudo-class
At Risk: the '':read-write'' pseudo-class
Ignored Terms: function token, Document, DocumentFragment, math, h1, shadow tree, query(), quirks mode, button, a, span, object, p, div, q, area, link, label, input, html, em, li, ol, pre, CSS Value Definition Syntax
Ignored Vars: identifier, extended filtering

spec:css-syntax-3; type:dfn; text:identifier

Introduction

• directly on an element to test whether it matches some criteria, such as in the element.matches() function defined in [[DOM]]
• applied to an entire tree of elements to filter it into a set of elements that match the criteria, such as in the document.queryAll() function defined in [[DOM]] or the selector of a CSS style rule.
• used "in reverse" to generate markup that would match a given selector, such as in HAML or Zen Coding

Module Interactions

Selectors Overview

Dynamic vs Static Selector Profiles

dynamic profile

The dynamic profile is appropriate for use in any context, including dynamic browser CSS selector matching. It includes every selector defined in this document, except for:

• The '':has()'' pseudo-class

static profile

The static profile is appropriate for contexts which aren't extremely performance sensitive; in particular, it's appropriate for contexts which evaluate selectors against a static document tree. For example, the {{Element/query()}} method defined in [[DOM]] should use the static profile. It includes all of the selectors defined in this document.

The categorization of things into the "dynamic" or "static" profiles needs implementor review. If some things currently not in the dynamic profile can reasonably be done in CSS Selectors, we should move them.

Selector Syntax and Structure

Structure and Terminology

• For a simple selector, it is any element represented by that selector.
• For a compound selector, it is any element that matches all of its composite simple selectors.
• For a complex selector, it is any element that matches the last compound selector in the selector.
• For a selector list, it is any element that matches any of the selectors in the list.

Data Model

• The element's type (also known as its tag name).
• The element's namespace.
• An ID.
• Classes (named groups) to which it belongs.
• Attributes, which are name-value pairs.

Scoped Selectors

Relative Selectors

Absolutizing a Relative Selector

1. If the selector starts with a child combinator, remove the child combinator. The selector is now absolute, with the additional constraint that the first compound selector in the selector only matches elements without a parent.
2. Otherwise, if the selector starts with any combinator other than the white space form of the descendant combinator, change the selector to '':not(*)''. This is the shortest selector that is valid, but guaranteed to match nothing.
3. Otherwise, the selector is already absolute.

1. If the selector starts with a combinator other than the white space form of the descendant combinator, prepend '':scope'' as the initial compound selector.
2. Otherwise, if the selector does not contain any instance of the '':scope'' pseudo-class (either at the top-level or as an argument to a functional pseudo-class), prepend '':scope'' followed by the white space form of the descendant combinator.
3. Otherwise, the selector is already absolute.

Pseudo-classes

For example, '':valid'' is a regular pseudo-class, and '':lang()'' is a functional pseudo-class. Like all CSS keywords, pseudo-class names are ASCII case-insensitive. No white space is allowed between the colon and the name of the pseudo-class, nor, as usual for CSS syntax, between a functional pseudo-class’s name and its opening parenthesis (which thus form a CSS function token). Also as usual, white space is allowed around the arguments inside the parentheses of a functional pseudo-class unless otherwise specified. Like other simple selectors, pseudo-classes are allowed in all compound selectors contained in a selector, and must follow the type selector or universal selector, if present. Note: Some pseudo-classes are mutually exclusive (such that a compound selector containing them, while valid, will never match anything), while others can apply simultaneously to the same element.

Pseudo-elements

Syntax

Binding to the Document Tree

Pseudo-classing Pseudo-elements

Internal Structure

		<div>
			<span>foo</span>
			<"shadow root">
				<content></content>
			</"shadow root">
		</div>
		

Characters and case sensitivity

Declaring Namespace Prefixes

Invalid Selectors and Error Handling

• a parsing error in a selector, e.g. an unrecognized token or a token which is not allowed at the current parsing point, causes that selector to be invalid.
• a simple selector containing an undeclared namespace prefix is invalid
• a selector containing an invalid simple selector, an invalid combinator or an invalid token is invalid.
• a selector list containing an invalid selector is invalid.
• an empty selector, i.e. one that contains no compound selector, is invalid.

Logical Combinations

Selector Lists

		h1 { font-family: sans-serif }
		h2 { font-family: sans-serif }
		h3 { font-family: sans-serif }
		

h1, h2, h3 { font-family: sans-serif }
		

		h1 { font-family: sans-serif }
		h2..foo { font-family: sans-serif }
		h3 { font-family: sans-serif }
		

h1, h2..foo, h3 { font-family: sans-serif } 

The Matches-any Pseudo-class: '':matches()''

*|*:matches(:hover, :focus) 

*|*:matches(*:hover, *:focus) 

The Negation Pseudo-class: '':not()''

button:not(\[DISABLED]) 

*:not(FOO)

html|*:not(:link):not(:visited)

The Relational Pseudo-class: '':has()''

a:has(> img)

dt:has(+ dt)

section:not(:has(h1, h2, h3, h4, h5, h6))

section:has(:not(h1, h2, h3, h4, h5, h6))

Elemental selectors

Type (tag name) selector

Universal selector

Namespaces in Elemental Selectors

ns|E

elements with name E in namespace ns

*|E

elements with name E in any namespace, including those without a namespace

|E

elements with name E without a namespace

E

if no default namespace has been declared for selectors, this is equivalent to *|E. Otherwise it is equivalent to ns|E where ns is the default namespace.

		@namespace foo url(http://www.example.com);
		foo|h1 { color: blue }  /* first rule */
		foo|* { color: yellow } /* second rule */
		|h1 { color: red }      /* ...*/
		*|h1 { color: green }
		h1 { color: green }
		

		@namespace url("http://example.com/foo");

		.special { ... }
		

Attribute selectors

Add comma-separated syntax for multiple-value matching? e.g. [rel ~= next, prev, up, first, last]

Attribute presence and value selectors

''[att]''

Represents an element with the att attribute, whatever the value of the attribute.

[att=val]

Represents an element with the att attribute whose value is exactly "val".

[att~=val]

Represents an element with the att attribute whose value is a whitespace-separated list of words, one of which is exactly "val". If "val" contains whitespace, it will never represent anything (since the words are separated by spaces). Also if "val" is the empty string, it will never represent anything.

[att|=val]

Represents an element with the att attribute, its value either being exactly "val" or beginning with "val" immediately followed by "-" (U+002D). This is primarily intended to allow language subcode matches (e.g., the hreflang attribute on the a element in HTML) as described in BCP 47 ([[BCP47]]) or its successor. For lang (or xml:lang) language subcode matching, please see the '':lang'' pseudo-class.

h1[title]

span[class="example"]

span[hello="Cleveland"][goodbye="Columbus"]

		a[rel~="copyright"] { ... }
		a[href="http://www.w3.org/"] { ... }
		

a[hreflang=fr] 

a[hreflang|="en"] 

		DIALOGUE[character=romeo]
		DIALOGUE[character=juliet]
		

object[type^="image/"] 

a[href$=".html"] 

p[title*="hello"] 

[frame=hsides i] { border-style: solid none; } 

		@namespace foo "http://www.example.com";
		[foo|att=val] { color: blue }
		[*|att] { color: yellow }
		[|att] { color: green }
		[att] { color: green }
		

<!ATTLIST EXAMPLE radix (decimal,octal) "decimal"> 

		EXAMPLE[radix=decimal] { /*... default property settings ...*/ }
		EXAMPLE[radix=octal]   { /*... other settings...*/ }
		

		EXAMPLE                { /*... default property settings ...*/ }
		EXAMPLE[radix=octal]   { /*... other settings...*/ }
		

*.pastoral { color: green }  /* all elements with class~=pastoral */ 

.pastoral { color: green }  /* all elements with class~=pastoral */ 

H1.pastoral { color: green }  /* H1 elements with class~=pastoral */ 

		<H1>Not green</H1>
		<H1 class="pastoral">Very green</H1>
		

p.pastoral.marine { color: green } 

h1#chapter1 

#chapter1 

*#z98y 

		html:lang(fr-be)
		html:lang(de)
		:lang(fr-be) > q
		:lang(de) > q
		

		<body lang=fr>
		  <p>Je suis français.</p>
		</body>
		

.footnote:visited 

p.note:target 

		:target { color : red }
		:target::before { content : url(target.png) }
		

		a:link    /* unvisited links */
		a:visited /* visited links */
		a:hover   /* user hovers */
		a:active  /* active links */
		

		a:focus
		a:focus:hover
		

:drop( [ active || valid || invalid ]? ) 

		:current(p, li, dt, dd) {
		  background: yellow;
		}
		

input[type=checkbox]:not(:checked)

		<form>
		  <label>
		    Volume:
		    <input name='vol' type=number min=0 max=10 value=11>
		  </label>
		  ...
		</form>
		

<p></p>

<foo>bar</foo>

<foo><bar>bla</bar></foo>

<foo>this is not <bar>:empty</bar></foo>

<p>
</p>

		:nth-child(even)   /* represents the 2nd, 4th, 6th, etc elements
		:nth-child(10n-1)  /* represents the 9th, 19th, 29th, etc elements */
		:nth-child(10n+9)  /* Same */
		:nth-child(10n+-1) /* Syntactically invalid, and would be ignored */
		

:nth-child(-n+3 of li.important)

li.important:nth-child(-n+3)

		tr {
			background: white;
		}
		tr:nth-child(even) {
			background: silver;
		}
		

		tr {
			background: white;
		}
		tr:nth-child(even of :not([hidden])) {
			background: silver;
		}
		

		tr:nth-last-child(-n+2)    /* represents the two last rows of an HTML table */

		foo:nth-last-child(odd)    /* represents all odd foo elements in their parent element,
		                              counting from the last one */
		

div > p:first-child

		<p> The last P before the note.</p>
		<div class="note">
			 <p> The first P inside the note.</p>
		</div>
		

		<p> The last P before the note.</p>
		<div class="note">
			 <h2> Note </h2>
			 <p> The first P inside the note.</p>
		</div>
		

		* > a:first-child /* a is first child of any element */
		a:first-child /* Same (assuming a is not the root element) */
		

ol > li:last-child

		img:nth-of-type(2n+1) { float: right; }
		img:nth-of-type(2n) { float: left; }
		

body > h2:nth-of-type(n+2):nth-last-of-type(n+2) 

body > h2:not(:first-of-type):not(:last-of-type) 

dl dt:first-of-type

		<dl>
		  <dt>gigogne</dt>
		  <dd>
		    <dl>
		      <dt>fusée</dt>
		      <dd>multistage rocket</dd>
		      <dt>table</dt>
		      <dd>nest of tables</dd>
		    </dl>
		  </dd>
		</dl>
		

tr > td:last-of-type

h1 em

		<h1>This <span class="myclass">headline
		is <em>very</em> important</span></h1>
		

div * p

div p *[href]

body > p

div ol>li p

math + p

h1.opener + h2

h1 ~ pre

		<h1>Definition of the function a</h1>
		<p>Function a(x) has to be applied to all figures in the table.</p>
		<pre>function a(x) = 12x/13.5</pre>
		

		col.selected || td {
			background: gray;
			color: white;
			font-weight: bold;
		}
		

		<table>
			<col span="2">
			<col class="selected">
			<tr><td>A <td>B <td>C
			<tr><td colspan="2">D <td>E
			<tr><td>F <td colspan="2">G
		</table>
		

		*               /* a=0 b=0 c=0 */
		LI              /* a=0 b=0 c=1 */
		UL LI           /* a=0 b=0 c=2 */
		UL OL+LI        /* a=0 b=0 c=3 */
		H1 + *[REL=up]  /* a=0 b=1 c=1 */
		UL OL LI.red    /* a=0 b=1 c=3 */
		LI.red.level    /* a=0 b=2 c=1 */
		#x34y           /* a=1 b=0 c=0 */
		#s12:not(FOO)   /* a=1 b=0 c=1 */
		.foo :matches(.bar, #baz)
		                /* Either a=1 b=1 c=0
		                   or a=0 b=2 c=0, depending
		                   on the element being matched. */
		

	<selector-list> = <>

	<complex-selector-list> = <>#

	<compound-selector-list> = <>#

	<simple-selector-list> = <>#

	<relative-selector-list> = <>#

	<complex-selector> = <> [ <>? <> ]*

	<relative-selector> = <>? <>

	<combinator> = '>>' | '>' | '+' | '~' | <>

	<compound-selector> = <>+

	<simple-selector> = <> | <> |
	                    <> | <> |
	                    <> | <>

	<type-selector> = <> | <> '*'

	<ns-prefix> = [ <> | '*' ]? '|'

	<wq-name> = <>? <>

	<id-selector> = <>

	<class-selector> = '.' <>

	<attribute-selector> = '[' <> ']' |
	                       '[' <> <> [ <> | <> ] <>? ']'

	<attr-matcher> = '=' | <> | <> | <> |
	                 <> | <>

	<attr-modifier> = i

	<pseudo-class-selector> = ':' <> |
	                          ':' <> <> ')'

	<pseudo-element-selector> = ':' <>