Abstract

CSS (Cascading Style Sheets) is a language for describing the rendering
of HTML and XML documents on screen, on paper, in speech, etc. To bind
style properties to elements in the document, it uses selectors,
which are patterns that match to elements. This draft describes the selectors
that are proposed for CSS level 3. It includes and extends the selectors
of CSS level 2.

Status of this document

This document is a draft of one of the "modules" for the upcoming CSS3
specification. It not only describes the selectors that already exist in
CSS1
and CSS2, but also proposes
new selectors for CSS3 as well as for other languages that may need them.
The Working Group doesn't expect that all implementations of CSS3 will
have to implement all types of selectors. Instead, there will probably
be a small number of variants of CSS3, so-called "profiles". For example,
it may be that only the profile for non-interactive user agents will include
all of the proposed selectors.

The current draft is the result of the merging of relevant parts of
the following Working Drafts:

This document is a working draft of the CSS & FP working group
which is part of the style
activity.

The working group would like to receive feedback:
comments on this draft may be send to the editor, discussion takes place
on the (archived)
public mailing list www-style@w3.org (see instructions). W3C Members can also send comments directly to the CSS & FP working group.

This working draft may be updated, replaced or rendered obsolete by
other W3C documents at any time. It is inappropriate to use W3C
Working Drafts as reference material or to cite them as other than
"work in progress". Its publication does not imply endorsement by the
W3C membership or the CSS &amp FP Working Group (members only).

To find the latest version of this working draft, please follow
the "Latest version" link above, or visit the list of W3C Technical Reports.

Members of the CSS+FP Working Group proposed during the Clamart meeting
to modularize the CSS specification.

This modularization, and the externalization of the general syntax,
of CSS will reduce the size of the spec and allow new types of specifications
to use selectors and/or CSS general syntax. For instance behaviours or
tree transformations.

2. Selectors

A W3C selector represents a structure. This structure can be understood
for instance as a condition (e.g. in a CSS rule) that determines which
elements in the document tree are matched by this selector, or as a flat
description of the HTML or XML fragment corresponding to that structure.

Combinators are: whitespace, ">", "+" and
"~". Whitespace may appear between a combinator and the simple
selectors around it. Only the characters "space" (Unicode code 32), "tab"
(9), "line feed" (10), "carriage return" (13), and "form feed" (12) can
occur in whitespace. Other space-like characters, such as "em-space" (8195)
and "ideographic space" (12288), are never part of whites-pace.

The subjects of the selector are
the most important elements represented by the selector. By default, the
subjects of a selector are the elements represented by the last sequence
of simple selectors in the selector. The :subject
pseudo-class can modify this default behavior.

Examples:

The following selector represents a list item LI unique child
of an ordered list OL:

OL > LI:only-child

but the following one represents an ordered list OL having a unique
child, that child being a LI:

OL:subject > LI:only-child

The structures represented by these two selectors are the same, but the
subjects of the selectors are not.

Warning : the equivalence is true in this example because all selectors are valid selectors. If one (or more) of these selectors is invalid, the group made of the three selectors is itself invalid, invalidating the rule
; then the equivalence is false.

Type selectors allow an optional namespace component. A namespace prefix
that has been previously declared (via a @namespace at-rule) may
be prepended to the element name separated by the namespace separator "|".
The namespace component may be left empty to indicate that the selector
is only to represent elements with no declared namespace. Furthermore,
an asterisk may be used for the namespace prefix, indicating that the selector
is to represent elements in any namespace (including elements with no namespace).
Element type selectors that have no namespace component (no namespace separator),
are considered to represent elements without regard to the element's namespace
(equivalent to "*|") unless a default namespace has been declared,
in that case, the selector will represent only elements in the default
namespace.

An alternative approach would be to define element type selectors that
have no namespace component to match only elements that have no namespace
(unless a default namespace has been declared in the CSS). This would make
the selector "h1" equivalent to the selector "|h1" as
opposed to "*|h1". The downside to this approach is that legacy
style sheets (those written without any namespace constructs) will fail
to match in all XML documents where namespaces are used throughout, i.e.
all XHTML documents.

It should be noted that if a namespace prefix used in a selector has
not been previously declared, then the selector must be considered invalid
and the entire style rule will be ignored in accordance with the standard
error handling rules.

It should further be noted that in a namespace aware client, element
type selectors will only match against the local
part of the element's qualified
name. See below
for notes about matching behaviors in down-level clients.

The universal selector, written "*", represents
the qualified name of any element type. It represents then any single element
in the document tree in any namespace (including those without any declared
namespace).

If the universal selector is not the only component of a simple selector,
the * may be omitted. For example:

*[LANG=fr] and [LANG=fr] are equivalent,

*.warning and .warning are equivalent,

*#myid and #myid are equivalent.

Warning : even if compatibility reasons with existing stylesheets
allow this omission of the universal selector, it is recommended not omitting
it.

Represents the att attribute, its value being a space-separated
list of words, one of which is exactly "val". If this selector is used,
the words in the value must not contain spaces (since they are separated
by spaces).

[att|=val]

Represents the att attribute, its value being a hyphen-separated
list of words, beginning with "val". The match always starts at the beginning
of the attribute value. This is primarily intended to allow language subcode
matches (e.g., the LANG attribute in HTML) as described in RFC
1766 ([RFC1766]).

Attribute values must be identifiers or strings. The case-sensitivity of
attribute names and values in selectors depends on the document language.

Example(s):

For example, the following attribute selector represents a H1
element that carries the TITLE attribute, whatever its value:

H1[TITLE]

Example(s):

In the following example, the selector represents a SPAN element
whose class attribute has exactly the value "example":

SPAN[class=example]

Multiple attribute selectors can be used to represent several attributes
of an element, or even several times the same attribute.

The following selectors illustrate the differences between "=" and "~=".
The first selector will represent, for example, the value "copyright copyleft
copyeditor" for the rel attribute. The second selector will only
represent a A with the href attribute having the exact
value "http://www.w3.org/".

A[rel~="copyright"]
A[href="http://www.w3.org/"]

Example(s):

The following selector represents an arbitrary element for which the
value of the lang attribute is "fr" (i.e., the language is French).

*[LANG=fr]

Example(s):

The following selector represent an arbitrary element for which the
values of the lang attribute begins with "en", including "en",
"en-US", and "en-cockney":

*[LANG|="en"]

Example(s):

Similarly, the following selectors represents a DIALOGUE element
having two different values for the same attribute character:

Attribute selectors allow an optional namespace component to the attribute
name. A namespace prefix that has been previously declared (via a @namespace
at-rule) may be prepended to the attribute name separated by the namespace
separator "|". In keeping with the Namespaces in the XML recommendation,
default namespaces do not apply to attributes, therefore attribute selectors
without a namespace component apply only to attributes that have no declared
namespace (equivalent to "|attr"). An asterisk may be used for
the namespace prefix indicating that the selector is to match all attribute
names without regard to the attribute's namespace.

Attribute selectors represent attribute values in the document tree. Default
attribute values may be defined in a DTD or elsewhere. W3C selectors should
be implemented so that they work even if the default values are not included
in the document tree.

Example(s):

For example, consider an element EXAMPLE with an attribute
"notation" that has a default value of "decimal". The DTD fragment might be

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

If the selectors represent an EXAMPLE element when the value of
the attribute is explicitely set:

EXAMPLE[notation=decimal]
EXAMPLE[notation=octal]

then to represent the case where this attribute is set by default, and
not explicitly, the following selector might be used:

Working with HTML, authors may use the dot (.) notation as an
alternative to the ~= notation when representing the class
attribute. Thus, for HTML, DIV.value and DIV[class~=value]
have the same meaning. The attribute value must immediately follow the
".".

Example(s):

For example, we can represent an arbitrary element with class~="pastoral"
as follows:

*.pastoral

or just

.pastoral

The following selector represents a H1 element with class~="pastoral":

H1.pastoral

Example(s):

For example, the following selector represents a P element
whose class attribute has been assigned a list of space-separated
values that includes "pastoral" and "marine":

P.pastoral.marine

This selector represents a P with class="pastoral blue aqua
marine" but does not with class="pastoral blue".

Document languages may contain attributes that are declared to be of type
ID. What makes attributes of type ID special is that no two such attributes
can have the same value; whatever the document language, an ID
attribute can be used to uniquely identify its element. In HTML all ID
attributes are named "id"; XML applications may name ID attributes
differently, but the same restriction applies.

The ID attribute of a document language allows authors to assign
an identifier to one element instance in the document tree. W3C ID selectors
represent an element instance based on its identifier. An ID selector contains
a "#" immediately followed by the ID value.

Example(s):

The following ID selector represent the H1 element whose ID
attribute has the value "chapter1":

H1#chapter1

The following selector represents the arbitrary element that has the ID
value "z98y".

*#z98y

Note. In XML 1.0 [XML10],
the information about which attribute contains an element's IDs is contained
in a DTD. When parsing XML, UAs do not always read the DTD, and thus may
not know what the ID of an element is. If a style sheet designer knows
or suspects that this will be the case, he should use normal attribute
selectors instead: [name=p371] instead of #p371. Of course,
elements in XML 1.0 documents without a DTD do not have IDs at all.

Pseudo-class concept is introduced to permit selection based on information
that lies outside of the document tree or that cannot be expressed using
the other simple selectors.

A pseudo-class always contains a colon (:) followed by the
name of the pseudo-class and optionnally by a value between parenthesis.

Pseudo-classes are allowed in all sequences of simple selectors contained
in a selector. Pseudo-classes are allowed anywhere in sequences of simple
selectors, after the leading type selector or universal selector (eventually
omitted). Pseudo-class names are case-insensitive. Some pseudo-classes
are mutually exclusive, while others can be applied simultaneously to the
same element.

Dynamic pseudo-classes classify elements on characteristics other than
their name, attributes or content; in principle characteristics that cannot
be deduced from the document tree. Dynamic pseudo-classes may be dynamic,
in the sense that an element may acquire or lose a pseudo-class while a
user interacts with the document.

Dynamic pseudo-classes do not appear in the document source or document
tree.

Interactive user agents sometimes change the rendering in response to user
actions. W3C selectors provide three pseudo-classes for the selection of
an element the user is acting on.

The :hover pseudo-class applies while the user designates an element (with some pointing device), but does not activate it. For example, a visual user agent could apply this pseudo-class when the cursor (mouse pointer)
hovers over a box generated by the element. User agents not supporting
interactive
media do not have to support this pseudo-class. Some conforming user
agents supporting interactive
media may not be able to support this pseudo-class (e.g., a pen device).

The :active pseudo-class applies while an element is being activated by the user. For example, between the times the user presses the mouse button and releases it.

The :focus pseudo-class applies while an element has the focus
(accepts keyboard events or other forms of text input).

Only elements whose 'user-input' property (see [UI]) has the value of "enabled" can become :active or acquire :focus.

These pseudo-classes are not mutually exclusive. An element may match
several of them at the same time.

If the document language specifies how the human language of an element
is determined, it is possible to write selectors that represent an element
based on its language. For example, in HTML [HTML40],
the language is determined by a combination of the LANG attribute,
the META element, and possibly by information from the protocol
(such as HTTP headers). XML uses an attribute called XML:LANG,
and there may be other document language-specific methods for determining
the language.

The pseudo-class :lang(C) represents an element that is in
language C. Here is a C language code as specified in HTML 4.0 [HTML40]
and RFC 1766 [RFC1766].
It is matched the same way as for the '|='
operator.

Example(s):

The two following selectors represent an HTML document that is in French
or German. The two next selectors represent Q quotations in an
arbitrary element in French or German.

The purpose of the :enabled pseudo-class is to allow authors to
customize the look of user interface elements which are enabled - which
the user can select/activate in some fashion (e.g. clicking on a button
with a mouse). There is a need for such a pseudo-class because as of yet
there is no way to programmatically specify the default appearance of say,
an enabled INPUT element without also specifying what it would look like
when it was disabled.

Similar to :enabled, :disabled allows the author to
specify precisely how a disabled or inactive user interface element should
look.

It should be noted that most elements will be neither enabled nor disabled.
An element is enabled if the user can either activate it or transfer the
focus to it. An element is disabled if it could be enabled, but the user
cannot presently activate it or transfer focus to it.

The :checked pseudo-class only applies to elements which are 'user-input: enabled' or 'user-input : disabled' (see [UI] for the 'user-input' property).
Radio and checkbox elements can be toggled by the user. Some menu items
are "checked" when the user selects them. When such elements are toggled
"on" the :checked pseudo-class applies. The :checked
pseudo-class initially applies to such elements that have the HTML4 SELECTED
attribute as described in Section
17.2.1 of HTML4, but of course the user can toggle "off" such elements
in which case the :checked pseudo-class would no longer apply.
While the :checked pseudo-class is dynamic in nature, and is altered
by user action, since it can also be based on the presence of the semantic
HTML4 SELECTED attribute, it applies to all media.

The :indeterminate pseudo-class only applies to elements which are 'user-input: enabled' or 'user-input: disabled' (see [UI] for the 'user-input' property). Radio and checkbox elements can be toggled by the user, but are sometimes in an indeterminate state, neither checked nor unchecked. This can be due to an element attribute, or DOM manipulation. The :indeterminate pseudo-class applies to such elements. While the :indeterminate pseudo-class is dynamic in nature, and is altered by user action, since it can also be based on the presence of an element attribute, it applies to all media.

W3C selectors introduce the concept of structural pseudo-classes
to permit selection based on extra information that lies in the document
tree but cannot be represented by other simple selectors or combinators.

Note that standalone PCDATA are not counted when calculating the position
of an element in the list of children of its parent. When calculating the
position of an element in the list of children of its parent, the index
numbering starts at 1.

The :root pseudo-class represents an element that is the root
of the document. In HTML 4, this is the HTML element. In XML,
it is whatever is appropriate for the dtd/scheme/namespace for that XML
document.

Pseudo-elements create abstractions about the document tree beyond those
specified by the document language. For instance, document languages do
not offer mechanisms to access the first letter or first line of an element's
content. Pseudo-elements allow designers to refer to this otherwise inaccessible
information. Pseudo-elements may also provide designers a way to refer
to content that does not exist in the source document (e.g., the :before
and :after pseudo-elements give access to generated content).

A pseudo-element always contains a colon (:) followed by the
name of the pseudo-element.

Pseudo-elements may only appear in the sequence of simple selectors
that represents the subjects
of the selector.

The :selection pseudo-element applies to the portion of a document
that has been highlighted by the user. This also applies, for example,
to selected text within an editable text field. Only elements that have
a user-select other than 'none' can have a :selection. This pseudo-element should not be confused with the :checked pseudo-class (which used to be named :selected) or the :selected pseudo-class in the Selectors Proposal.

Although the :selection pseudo-element is dynamic in nature,
and is altered by user action, it is reasonable to expect that when a UA
rerenders to a static medium (such as a printed page) which was originally
rendered to a dynamic medium (like screen), the UA may wish to transfer
the current :selection state to that other medium, and have all
the appropriate formatting and rendering take effect as well. This is not
required - UAs may omit the :selection pseudo-element for static
media.

Authors can specify the style and location of a generated menu with the :menu pseudo-element. It is treated as a child of the element (and therefore inherits all styling by default - similar to :before and :after), and absolutely positioned at 0,0 with respect to the content top left corner of the element. It is made "visibility:visible" when the element itself is :active, and is "visibility:hidden" otherwise. It contains a copy of all the contents of the element itself.

At times, authors may want selectors to describe an element that is the
descendant of another element in the document tree (e.g., "an EM
element that is contained by an H1 element"). Descendant combinators
express such a relationship. A descendant combinator is a whitespace
that separates two sequences of simple selectors. A selector of the form
"A B" represents an element B that is an arbitrary descendant
of some ancestor element A.

Example(s):

For example, consider the following selector:

H1 EM

It is a correct and valid, but partial, description of the following fragment:

A child combinator describes a childhood relationship between two elements. A child combinator is made of the ">" character and separates two sequences of simple selectors.

Example(s):

The following selector represents a P element that is child
of BODY:

BODY > P

Example(s):

The following example combines descendant combinators and child combinators.

DIV OL>LI P

It represents a P element that is a descendant of an LI;
the LI element must be the child of an OL element; the
OL element must be a descendant of a DIV. Notice that the optional whitespace around the ">" combinator has been left out.

For information on selecting the first child of an element, please see
the section on the :first-child
pseudo-class above.

Direct adjacent combinators are made of the "+" character that
separates two sequences of simple selectors. The elements represented by
the two sequences share the same parent in the document tree and the element
represented by the first sequence immediately precedes the element represented
by the second one.

Example(s):

Thus, the following selector represents a P element immediately
following a MATH element:

MATH + P

Example(s):

The following selector is similar to the one in the previous example,
except that it adds an attribute selector. Thus, it adds a constraint to
the H1 element that must have class="opener":

Indirect adjacent combinators are made of the "~" character that
separates two sequences of simple selectors. The elements represented by
the two sequences share the same parent in the document tree and the element
represented by the first sequence precedes (not necessarily immediately)
the element represented by the second one.

Example(s):

H1 ~ PRE

represents a PRE element following a H1. It is a correct
and valid, but partial, description of:

The grammar below defines the syntax of W3C selectors. It is globally LL(1)
and can be locally LL(2) (but note that most UA's should not use it directly,
since it doesn't express the parsing conventions). The format of the productions
is optimized for human consumption and some shorthand notations beyond
Yacc (see [YACC])
is used:

The following is the tokenizer,
written in Flex (see [FLEX])
notation. The tokenizer is case-insensitive.

The two occurrences of "\377" represent the highest character number
that current versions of Flex can deal with (decimal 255). They should
be read as "\4177777" (decimal 1114111), which is the highest possible
code point in Unicode/ISO-10646.

An important issue is the interaction of CSS selectors with XML documents
in web clients that were produced prior to this document. Unfortunately,
due to the fact that namespaces must be matched based on the URI which
identifies the namespace, not the namespace prefix, some mechanism is required
to identify namespaces in CSS by their URI as well. Without such a mechanism,
it is impossible to construct a CSS stylesheet which will properly match
selectors in all cases against a random set of XML documents. However,
given complete knowledge of the XML document to which a stylesheet is to
be applied, and a limited use of namespaces within the XML document, it
is possible to construct a stylesheet in which selectors would match elements
and attributes correctly.

It should be noted that a down-level CSS client will (if it properly
conforms to CSS forward compatible parsing rules) ignore all @namespace at-rules, as well as all style rules that make use of namespace qualified element type or attribute selectors. The syntax of delimiting namespace prefixes in CSS was deliberately chosen so that down-level CSS clients would ignore the style rules rather than possibly match them incorrectly.

The use of default namespaces in CSS makes it possible to write element
type selectors that will function in both namespace aware CSS clients as
well as down-level clients. It should be noted that down-level clients
may incorrectly match selectors against XML elements in other namespaces.

The following are scenarios and examples in which it is possible to
construct stylesheets which would function properly in web clients that
do not implement this proposal.

The XML document does not use namespaces.

In this case, it is obviously not necessary to declare or use namespaces
in the stylesheet. Standard CSS element type and attribute selectors will
function adequately in a down-level client.

In a CSS namespace aware client, the default behavior of element selectors
matching without regard to namespace will function properly against all
elements, since no namespaces are present. However, the use of specific
element type selectors that match only elements that have no namespace
("|name") will guarantee that selectors will match only XML elements
that do not have a declared namespace.

The XML document defines a single, default namespace used throughout the
document. No namespace prefixes are used in element names.

In this case, a down-level client will function as if namespaces were not
used in the XML document at all. Standard CSS element type and attribute
selectors will match against all elements.

The XML document does not use a default namespace, all namespace
prefixes used are known to the stylesheet author and there is a direct
mapping between namespace prefixes and namespace URIs (a given prefix may
only be mapped to one namespace URI throughout the XML document, there
may be multiple prefixes mapped to the same URI).

In this case, the down-level client will view and match element type and
attribute selectors based on their fully qualified name, not the local
part as outlined in the Type
selectors and Namespaces section. CSS selectors may be declared using
an escaped colon "\:" to describe the fully qualified names, i.e.
"html\:h1" will match <html:h1>. Selectors using the
qualified name will only match XML elements that use the same prefix. Other
namespace prefixes used in the XML that are mapped to the same URI will
not match as expected unless additional CSS style rules are declared for
them.

Note that selectors declared in this fashion will only match in
down-level clients. A CSS namespace aware client will match element type
and attribute selectors based on the name's local part. So selectors declared
with the fully qualified name will not match (unless there is no namespace
prefix in the fully qualified name, of course).

In other scenarios: when the namespace prefixes used in the XML are not
known in advance by the stylesheet author; or a combination of elements
with no namespace are used in conjunction with elements using a default
namespace; or the same namespace prefix is mapped to different namespace
URIs within the same document, or in different documents; it is impossible
to construct a CSS stylesheet that will function properly against all elements
in those documents, unless, the stylesheet is written using a namespace
URI syntax (as outlined in this document or similar) and the document is
processed by a CSS and XML namespace aware client.

some selectors and combinators are not allowed in fragment descriptions
on the right side of STTS declarations.

W3C selectors can be used in STTS in two different manners:

a selection mechanism equivalent to CSS selection mechanism : declarations
attached to a given selector are applied to elements matching that selector,

fragment descriptions that appear on the right side of declarations; restriction: selectors and combinators introducing ambiguity about the represented structure (descendant combinator for instance) are not allowed in fragment descriptions.