1.
Introduction
This section is not normative.
selector
is a boolean predicate
that takes an element in a tree structure
and tests whether the element matches the selector or not.
These expressions may be used for many things:
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
Emmet
Selectors Levels 1, 2, and 3 are defined as the subsets of selector
functionality defined in the
CSS1
CSS2.1
, and
Selectors Level 3
specifications, respectively. This module defines Selectors Level 4.
1.1.
Module Interactions
This module replaces the definitions of
and extends the set of selectors defined for CSS in
[SELECT]
and
[CSS21]
Pseudo-element selectors,
which define abstract elements in a rendering tree,
are not part of this specification:
their generic syntax is described here,
but, due to their close integration with the rendering model and irrelevance to other uses such as DOM queries,
they will be defined in other modules.
2.
Selectors Overview
This section is non-normative, as it merely summarizes the
following sections.
A selector represents a structure. This structure can be used as a
condition (e.g. in a CSS rule) that determines which elements a
selector matches in the document tree, or as a flat description of the
HTML or XML fragment corresponding to that structure.
Selectors may range from simple element names to rich contextual
representations.
The following table summarizes the Selector syntax:
Pattern
Represents
Section
Level
any element
§5.2 Universal selector
an element of type E
§5.1 Type (tag name) selector
E:not(
s1
s2
an E element that does not match either
compound selector
s1
or
compound selector
s2
§4.3 The Negation Pseudo-class: :not()
3/4
E:matches(
s1
s2
an E element that matches
compound selector
s1
and/or
compound selector
s2
§4.2 The Matches-any Pseudo-class: :matches()
E:something(
s1
s2
an E element that matches
compound selector
s1
and/or
compound selector
s2
but contributes no specificity.
§4.4 The Specificity-adjustment Pseudo-class: :something()
E:has(
rs1
rs2
an E element,
if either of the
relative selectors
rs1
or
rs2
when evaluated with E as the
:scope elements
match an element
§4.5 The Relational Pseudo-class: :has()
E.warning
an E element belonging to the class
warning
(the document language specifies how class is determined).
§6.6 Class selectors
E#myid
an E element with ID equal to
myid
§6.7 ID selectors
E[foo]
an E element with a
foo
attribute
§6 Attribute selectors
E[foo="bar"]
an E element whose
foo
attribute value is
exactly equal to
bar
§6 Attribute selectors
E[foo="bar" i]
an E element whose
foo
attribute value is
exactly equal to any (ASCII-range) case-permutation of
bar
§6.3 Case-sensitivity
E[foo~="bar"]
an E element whose
foo
attribute value is
a list of whitespace-separated values, one of which is
exactly equal to
bar
§6 Attribute selectors
E[foo^="bar"]
an E element whose
foo
attribute value
begins exactly with the string
bar
§6.2 Substring matching attribute selectors
E[foo$="bar"]
an E element whose
foo
attribute value
ends exactly with the string
bar
§6.2 Substring matching attribute selectors
E[foo*="bar"]
an E element whose
foo
attribute value
contains the substring
bar
§6.2 Substring matching attribute selectors
E[foo|="en"]
an E element whose
foo
attribute value is
a hyphen-separated list of values beginning with
en
§6 Attribute selectors
E:dir(ltr)
an element of type E in with left-to-right directionality
(the document language specifies how directionality is determined)
§7.1 The Directionality Pseudo-class: :dir()
E:lang(zh, "*-hant")
an element of type E tagged as being either in Chinese
(any dialect or writing system)
or otherwise written with traditional Chinese characters
§7.2 The Language Pseudo-class: :lang()
2/4
E:any-link
an E element being the source anchor of a hyperlink
§8.1 The Hyperlink Pseudo-class: :any-link
E:link
an E element being the source anchor of a hyperlink
of which the target is not yet visited
§8.2 The Link History Pseudo-classes: :link and :visited
E:visited
an E element being the source anchor of a hyperlink
of which the target is already visited
§8.2 The Link History Pseudo-classes: :link and :visited
E:local-link
an E element being the source anchor of a hyperlink
targetting the current URL
§8.3 The Local Link Pseudo-class: :local-link
E:target
an E element being the target of the current URL
§8.4 The Target Pseudo-class: :target
E:target-within
an E element that is the target of the current URL or contains an element that does.
§8.5 The Target Container Pseudo-class: :target-within
E:scope
an E element being a designated reference element
§8.6 The Reference Element Pseudo-class: :scope
E:current
an E element that is currently presented in a time-dimensional canvas
§10 Time-dimensional Pseudo-classes
E:current(
an E element that is the deepest
:current
element that
matches selector
§10 Time-dimensional Pseudo-classes
E:past
an E element that is in the past in a time-dimensional canvas
§10 Time-dimensional Pseudo-classes
E:future
an E element that is in the future in a time-dimensional canvas
§10 Time-dimensional Pseudo-classes
E:active
an E element that is in an activated state
§9 User Action Pseudo-classes
E:hover
an E element that is under the cursor,
or that has a descendant under the cursor
§9 User Action Pseudo-classes
E:focus
an E element that has user input focus
§9 User Action Pseudo-classes
E:focus-within
an E element that has user input focus or contains an element that has input focus.
§9.5 The Focus Container Pseudo-class: :focus-within
E:focus-visible
an E element that has user input focus,
and the UA has determined that a focus ring or other indicator
should be drawn for that element
§9 User Action Pseudo-classes
E:drop
an E element that can possibly receive a drop
§9.6 The Drop Target Pseudo-class: :drop and :drop()
E:drop(active)
an E element that is the current drop target for the item being dragged
§9.6 The Drop Target Pseudo-class: :drop and :drop()
E:drop(valid)
an E element that could receive the item currently being dragged
§9.6 The Drop Target Pseudo-class: :drop and :drop()
E:drop(invalid)
an E element that cannot receive the item currently being dragged, but could receive some other item
§9.6 The Drop Target Pseudo-class: :drop and :drop()
E:enabled
E:disabled
a user interface element E that is enabled or disabled, respectively
§12.1.1 The :enabled and :disabled Pseudo-classes
E:read-write
E:read-only
a user interface element E that is user alterable, or not
§12.1.2 The Mutability Pseudo-classes: :read-only and :read-write
3-UI/4
E:placeholder-shown
an input control currently showing placeholder text
§12.1.2 The Mutability Pseudo-classes: :read-only and :read-write
3-UI/4
E:default
a user interface element E that is the default item in a group of related choices
§12.1.4 The Default-option Pseudo-class: :default
3-UI/4
E:checked
a user interface element E that is checked/selected
(for instance a radio-button or checkbox)
§12.2.1 The Selected-option Pseudo-class: :checked
E:indeterminate
a user interface element E that is in an indeterminate state
(neither checked nor unchecked)
§12.2.2 The Indeterminate-value Pseudo-class: :indeterminate
E:valid
E:invalid
a user-input element E that meets, or doesn’t, its data validity semantics
§12.3.2 The Range Pseudo-classes: :in-range and :out-of-range
3-UI/4
E:in-range
E:out-of-range
a user-input element E whose value is in-range/out-of-range
§12.3.2 The Range Pseudo-classes: :in-range and :out-of-range
3-UI/4
E:required
E:optional
a user-input element E that requires/does not require input
§12.3.3 The Optionality Pseudo-classes: :required and :optional
3-UI/4
E:user-invalid
a user-altered user-input element E with incorrect input (invalid, out-of-range, omitted-but-required)
§12.3.4 The User-interaction Pseudo-class: :user-invalid
E:root
an E element, root of the document
§13 Tree-Structural pseudo-classes
E:empty
an E element that has no children (not even text nodes)
§13 Tree-Structural pseudo-classes
E:blank
an E element that has no content except maybe white space
§13 Tree-Structural pseudo-classes
E:nth-child(
[of
]?)
an E element, the
-th child of its parent matching
§13.4 Child-indexed Pseudo-classes
E:nth-last-child(
[of
]?)
an E element, the
-th child of its parent matching
counting from the last one
§13.4 Child-indexed Pseudo-classes
E:first-child
an E element, first child of its parent
§13.4 Child-indexed Pseudo-classes
E:last-child
an E element, last child of its parent
§13.4 Child-indexed Pseudo-classes
E:only-child
an E element, only child of its parent
§13.4 Child-indexed Pseudo-classes
E:nth-of-type(
an E element, the
-th sibling of its type
§13.5 Typed Child-indexed Pseudo-classes
E:nth-last-of-type(
an E element, the
-th sibling of its type,
counting from the last one
§13.5 Typed Child-indexed Pseudo-classes
E:first-of-type
an E element, first sibling of its type
§13.5 Typed Child-indexed Pseudo-classes
E:last-of-type
an E element, last sibling of its type
§13.5 Typed Child-indexed Pseudo-classes
E:only-of-type
an E element, only sibling of its type
§13.5 Typed Child-indexed Pseudo-classes
E F
an F element descendant of an E element
§14.1 Descendant combinator ( )
E > F
an F element child of an E element
§14.2 Child combinator (>)
E + F
an F element immediately preceded by an E element
§14.3 Next-sibling combinator (+)
E ~ F
an F element preceded by an E element
§14.4 Subsequent-sibling combinator (~)
F || E
an E element that represents a cell in a grid/table
belonging to a column represented by an element F
§15 Grid-Structural Selectors
E:nth-col(
an E element that represents a cell belonging to the
th column in a grid/table
§15 Grid-Structural Selectors
E:nth-last-col(
an E element that represents a cell belonging to the
th column in a grid/table, counting from the last one
§15 Grid-Structural Selectors
Note:
Some Level 4 selectors (noted above as "3-UI") were introduced in
[CSS3UI]
2.1.
Live
vs
Snapshot
Selector Profiles
Selectors are used in many different contexts,
with wildly varying performance characteristics.
Some powerful selectors are unfortunately too slow
to realistically include in the more performance-sensitive contexts.
To accommodate this, two profiles of the Selectors spec are defined:
live profile
The
live
profile is appropriate for use in any context,
including browser CSS selector matching, which is live.
It includes every selector defined in this document,
except for:
snapshot profile
The
snapshot
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
query()
method defined in
[DOM]
should use the
snapshot
profile.
It includes all of the selectors defined in this document.
CSS implementations conformant to Selectors Level 4 must use the
live
profile for CSS selection.
Implementations using the
live
profile must treat selectors that are not included in the profile
as unknown and invalid.
The categorization of things into the “live” or snapshot profiles needs implementor review.
If some things currently not in the live profile can reasonably be done in CSS Selectors,
we should move them.
3.
Selector Syntax and Structure
3.1.
Structure and Terminology
selector
represents
a particular pattern of element(s) in a tree structure.
The term
selector
can refer to a
simple selector
compound selector
complex selector
, or
selector list
The
subject of a selector
is
any element that selector is defined to be about;
that is, any element
matching
that
selector
simple selector
is a single condition on an element.
type selector
universal selector
attribute selector
class selector
ID selector
or
pseudo-class
is a
simple selector
(It is represented by

in the selectors
grammar
.)
A given element is said to
match
simple selector
when that
simple selector
as defined in this specification and in accordance with the
document language
accurately describes the element.
compound selector
is a sequence of
simple selectors
that are not separated by a
combinator
and represents a set of simultaneous conditions on a single element.
If it contains a
type selector
or
universal selector
that selector must come first in the sequence.
Only one type selector or universal selector is allowed in the sequence.
(A
compound selector
is represented by

in the selectors
grammar
.)
A given element is said to
match
compound selector
when it matches all
simple selectors
in the
compound selector
Note:
As whitespace represents the
descendant combinator
no whitespace is allowed between the
simple selectors
in a
compound selector
combinator
is a condition of relationship between two elements
represented by the
compound selectors
on either side.
Combinators in Selectors Level 4 include:
the
descendant combinator
(white space),
the
child combinator
(U+003E,
),
the
next-sibling combinator
(U+002B,
),
and the
subsequent-sibling combinator
(U+007E,
).
Two given elements are said to
match
combinator
when the condition of relationship between these elements is true.
complex selector
is
a sequence of one or more
compound selectors
separated by
combinators
It represents a set of simultaneous conditions
on a set of elements in the particular relationships
described by its
combinators
(Complex selectors are represented by

in the selectors
grammar
.)
A given element is said to
match
complex selector
when there exists a list of elements,
each matching a corresponding
compound selector
in the
complex selector
with their relationships matching the
combinators
between them,
and with the given element matching the last
compound selector
Note:
Thus, a selector consisting of a single
compound selector
matches any element satisfying the requirements
of its constituent
simple selectors
Prepending another
compound selector
and a
combinator
to a sequence imposes additional matching constraints,
such that the
subjects
of a
complex selector
are always
a subset of the elements represented by its last
compound selector
list of simple/compound/complex selectors
is a comma-separated list of
simple
compound
or
complex selectors
This is also called just a
selector list
when the type is either unimportant or specified in the surrounding prose;
if the type is important and unspecified,
it defaults to meaning a
list of complex selectors
(See
§4.1 Selector Lists
for additional information on
selector lists
and the various
<*-selector-list>
productions in the
grammar
for their formal syntax.)
A given element is said to
match
selector list
when it matches any (at least one) of the
selectors
in that
selector list
Pseudo-elements aren’t handled here, and should be.
3.2.
Data Model
Selectors are evaluated against an element tree such as the DOM.
[DOM]
Within this specification,
this may be referred to as the "document tree" or "source document".
Each element may have any of the following five aspects,
which can be selected against,
all of which are matched as strings:
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.
While individual elements may lack any of the above features,
some elements are
featureless
featureless
element does not match any selector at all,
except those it is explicitly defined to match.
If a given selector
is
allowed to match a
featureless
element,
it must do so while ignoring the default namespace.
[CSS3NAMESPACE]
Many of the selectors depend on the semantics of the
document language
(i.e. the language and semantics of the document tree)
and/or the semantics of the
host language
(i.e. the language that is using selectors syntax).
For example, the
:lang()
selector depends on the
document language
(e.g. HTML)
to define how an element is associated with a language.
As a slightly different example, the
::first-line
pseudo-element
depends on the
host language
(e.g. CSS)
to define what a
::first-line
pseudo-element represents
and what it can do.
3.3.
Scoped Selectors
Some host applications may choose to
scope
selectors
to a particular subtree or fragment of the document.
The root of the scoping subtree is called the
scoping root
and may be either a true element (the
scoping element
or a
virtual
one (such as a
DocumentFragment
).
When a selector is
scoped
it matches an element only if the element is a descendant of the
scoping root
(The rest of the selector can match unrestricted;
it’s only the final matched elements that must be within the scope.)
For example,
the
element.querySelector()
function defined in
[DOM]
allows the author to evaluate a
scoped
selector
relative to the
element
it’s called on.
A call like
widget
querySelector
"a"
will thus only find
elements inside of the
widget
element,
ignoring any other
s that might be scattered throughout the document.
Note:
If the context does not explicitly define any
:scope elements
for the selector,
the
scoping root
is a
:scope element
3.4.
Relative Selectors
Certain contexts may accept
relative selectors
which are a shorthand for selectors that represent elements relative to a
:scope element
(i.e. an element that matches
:scope
).
In a
relative selector
“:scope ” (the
:scope
pseudo-class followed by a space)
is implied at the beginning of each
complex selector
that does not already contain the
:scope
pseudo-class.
This allows the selector to begin syntactically with a
combinator
However, it must be
absolutized
before matching.
Relative selectors, once absolutized,
can additionally be
scoped
Relative selectors are represented by

in the selectors
grammar
3.4.1.
Absolutizing a Relative Selector
To
absolutize a relative selector
If there are no
:scope elements
and the selector is
scoped
to a
virtual scoping root
This needs a sane definition.
Otherwise:
If the selector starts with a
combinator
other than the white space form of the
descendant combinator
prepend
:scope
as the initial
compound selector
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
Otherwise, the selector is already absolute.
To
absolutize a relative selector list
absolutize each relative selector in the list.
3.5.
Pseudo-classes
Pseudo-classes
are
simple selectors
that permit selection based on
information that lies outside of the document tree
or that can be awkward or impossible to express using the other simple selectors.
They can also be dynamic,
in the sense that an element can acquire or lose a pseudo-class
while a user interacts with the document,
without the document itself changing.
Pseudo-classes
do not appear in or modify the document source or document tree.
The syntax of a
pseudo-class
consists of a ":" (U+003A COLON)
followed by the name of the
pseudo-class
as a CSS
identifier
and, in the case of a
functional pseudo-class
a pair of parentheses containing its arguments.
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.
3.6.
Pseudo-elements
Similar to how certain
pseudo-classes
represent additional state information
not directly present in the document tree,
pseudo-element
represents an
element
not directly present in the document tree.
They are used to create abstractions about the document tree
beyond those provided by the document tree.
For example,
pseudo-elements can be used to select portions of the document
that do not correspond to a document-language element
(including such ranges as don’t align to element boundaries or fit within its tree structure);
that represent content not in the document tree or in an alternate projection of the document tree;
or that rely on information provided by styling, layout, user interaction, and other processes that are not reflected in the document tree.
For instance, document languages do not offer mechanisms to access
the first letter or first line of an element’s content,
but there exist
pseudo-elements
::first-letter
and
::first-line
that allow those things to be styled.
Notice especially that in the case of
::first-line
which portion of content is represented by the pseudo-element
depends on layout information
that cannot be inferred from the document tree.
Pseudo-elements
can also represent content that doesn’t exist in the source document at all,
such as the
::before
and
::after
pseudo-elements
which allow additional content to be inserted before or after the contents of any element.
Like
pseudo-classes
pseudo-elements
do not appear in or modify the document source or document tree.
Accordingly, they also do not affect the interpretation of
structural pseudo-classes
or other selectors pertaining to their
originating element
or its tree.
The host language defines which pseudo-elements exist, their type, and their abilities.
Pseudo-elements that exist in CSS
are defined in
[CSS21]
(Level 2),
[SELECT]
(Level 3), and
[CSS-PSEUDO-4]
(Level 4).
3.6.1.
Syntax
The syntax of a
pseudo-element
is "::" (two U+003A COLON characters)
followed by the name of the
pseudo-element
as an
identifier
Pseudo-element
names are
ASCII case-insensitive
No
white space
is allowed between the two colons, or between the colons and the name.
Because
CSS Level 1
and
CSS Level 2
conflated pseudo-elements and pseudo-classes by sharing a single-colon syntax for both,
user agents must also accept the previous one-colon notation
for the Level 1 & 2 pseudo-elements
::before
::after
::first-line
, and
::first-letter
).
This compatibility notation is not allowed any other
pseudo-elements
However, as this syntax is deprecated,
authors should use the Level 3+ double-colon syntax for these
pseudo-elements
Pseudo-elements
are
featureless
and so can’t be matched by any other selector.
3.6.2.
Binding to the Document Tree
Pseudo-elements
do not exist independently in the tree:
they are always bound to another element on the page,
called their
originating element
Syntactically, a
pseudo-element
immediately follows
the
compound selector
representing its
originating element
If this
compound selector
is omitted,
it is assumed to be the
universal selector
For example, in the selector
div a::before
the
elements matched by the selector are the
originating elements
for the
::before
pseudo-elements attached to them.
The selector
::first-line
is equivalent to
*::first-line
which selects the
::first-line
pseudo-element on
every
element in the document.
When a
pseudo-element
is encountered in a selector,
the part of the selector before the
pseudo-element
selects the
originating element
for the
pseudo-element
the part of the selector after it, if any, applies to the
pseudo-element
itself.
(See below.)
3.6.3.
Pseudo-classing Pseudo-elements
pseudo-element
may be immediately followed
by any combination of the
user action pseudo-classes
in which case the
pseudo-element
is represented only when it is in the corresponding state.
Whether these pseudo-classes can match on the
pseudo-element
depends on the
pseudo-class
and
pseudo-element
’s definitions:
unless otherwise-specified, none of these
pseudo-classes
will match on the
pseudo-element
Clarify that
:not()
and
:matches()
can be used when containing above-mentioned pseudos.
For example, since the
:hover
pseudo-class specifies
that it can apply to any pseudo-element,
::first-line:hover
will match when the first line is hovered.
However, since neither
:focus
nor
::first-line
define that
:focus
can apply to
::first-line
the selector
::first-line:focus
will never match anything.
Does
::first-line:not(:focus)
match anything?
Notice that
::first-line:hover
is very different from
:hover::first-line
which matches the first line of any originating element that is hovered!
For example,
:hover::first-line
also matches the first line of a paragraph
when the second line of the paragraph is hovered,
whereas
::first-line:hover
only matches if the first line itself is hovered.
Note:
Note that, unless otherwise specified in a future specification,
pseudo-classes other than the
user action pseudo-classes
are not valid when compounded to a pseudo-element;
so, for example,
::before:first-child
is an invalid selector.
3.6.4.
Internal Structure
Some
pseudo-elements
are defined to have internal structure.
These
pseudo-elements
may be followed by child/descendant combinators
to express those relationships.
Selectors containing
combinators
after the pseudo-element
are otherwise invalid.
For example,
::first-letter + span
and
::first-letter em
are invalid selectors.
However, since
::shadow
is defined to have internal structure,
::shadow > p
is a valid selector.
Note:
A future specification may expand the capabilities of existing pseudo-elements,
so some of these currently-invalid selectors (e.g.
::first-line :any-link
may become valid in the future.
The children of such
pseudo-elements
can simultaneously be children of other elements, too.
However, at least in CSS, their rendering must be defined so as to maintain the tree-ness of the
box tree
For example,
the
::content
pseudo-element treats elements distributed to it as its children.
This means that, given the following fragment:

function a(x) = 12x/13.5