CSS Object Model (CSSOM)

1. Introduction

This document formally specifies the core features of the CSS Object Model (CSSOM). Other documents in the CSSOM family of specifications as well as other CSS related specifications define extensions to these core features.

The core features of the CSSOM are oriented towards providing basic capabilities to author-defined scripts to permit access to and manipulation of style related state information and processes.

The features defined below are fundamentally based on prior specifications of the W3C DOM Working Group, primarily [DOM]. The purposes of the present document are (1) to improve on that prior work by providing more technical specificity (so as to improve testability and interoperability), (2) to deprecate or remove certain less-widely implemented features no longer considered to be essential in this context, and (3) to newly specify certain extensions that have been or expected to be widely implemented.

2. Terminology

This specification employs certain terminology from the following documents: DOM, HTML, CSS Syntax, Encoding, URL, Fetch, Associating Style Sheets with XML documents and XML. [DOM] [HTML] [CSS3SYN] [ENCODING] [URL] [FETCH] [XML-STYLESHEET] [XML]

When this specification talks about object A where A is actually an interface, it generally means an object implementing interface A.

The terms set and unset to refer to the true and false values of binary flags or variables, respectively. These terms are also used as verbs in which case they refer to mutating some value to make it true or false, respectively.

The term supported styling language refers to CSS.

Note: If another styling language becomes supported in user agents, this specification is expected to be updated as necessary.

The term supported CSS property refers to a CSS property that the user agent implements, including any vendor-prefixed properties, but excluding custom properties. A supported CSS property must be in its lowercase form for the purpose of comparisons in this specification.

In this specification the ::before and ::after pseudo-elements are assumed to exist for all elements even if no box is generated for them.

When a method or an attribute is said to call another method or attribute, the user agent must invoke its internal API for that attribute or method so that e.g. the author can’t change the behavior by overriding attributes or methods with custom properties or functions in ECMAScript.

Unless otherwise stated, string comparisons are done in a case-sensitive manner.

2.1. Common Serializing Idioms

To escape a character means to create a string of "\" (U+005C), followed by the character.

To escape a character as code point means to create a string of "\" (U+005C), followed by the Unicode code point as the smallest possible number of hexadecimal digits in the range 0-9 a-f (U+0030 to U+0039 and U+0061 to U+0066) to represent the code point in base 16, followed by a single SPACE (U+0020).

To serialize an identifier means to create a string represented by the concatenation of, for each character of the identifier:

If the character is NULL (U+0000), then the REPLACEMENT CHARACTER (U+FFFD).
If the character is in the range [\1-\1f] (U+0001 to U+001F) or is U+007F, then the character escaped as code point.
If the character is the first character and is in the range [0-9] (U+0030 to U+0039), then the character escaped as code point.
If the character is the second character and is in the range [0-9] (U+0030 to U+0039) and the first character is a "-" (U+002D), then the character escaped as code point.
If the character is the first character and is a "-" (U+002D), and there is no second character, then the escaped character.
If the character is not handled by one of the above rules and is greater than or equal to U+0080, is "-" (U+002D) or "_" (U+005F), or is in one of the ranges [0-9] (U+0030 to U+0039), [A-Z] (U+0041 to U+005A), or [a-z] (U+0061 to U+007A), then the character itself.
Otherwise, the escaped character.

To serialize a function func, returning a string:

Let s be an empty string.
Serialize an identifier from func’s name, ASCII lowercased, and append the result to s.
Append "(" (U+0028) to s.
Serialize func’s contents, either as specified by the definition of func, or in the shortest form possible (akin to the principles captured by serialize a CSS value). Append the result to s.
Append ")" (U+0029) to s.
Return s.

To serialize a string means to create a string represented by '"' (U+0022), followed by the result of applying the rules below to each character of the given string, followed by '"' (U+0022):

If the character is NULL (U+0000), then the REPLACEMENT CHARACTER (U+FFFD).
If the character is in the range [\1-\1f] (U+0001 to U+001F) or is U+007F, the character escaped as code point.
If the character is '"' (U+0022) or "\" (U+005C), the escaped character.
Otherwise, the character itself.

Note: "'" (U+0027) is not escaped because strings are always serialized with '"' (U+0022).

To serialize a URL means to create a string represented by "url(", followed by the serialization of the URL as a string, followed by ")".

To serialize a LOCAL means to create a string represented by "local(", followed by the serialization of the LOCAL as a string, followed by ")".

To serialize a comma-separated list concatenate all items of the list in list order while separating them by ", ", i.e., COMMA (U+002C) followed by a single SPACE (U+0020).

To serialize a whitespace-separated list concatenate all items of the list in list order while separating them by " ", i.e., a single SPACE (U+0020).

Note: When serializing a list according to the above rules, extraneous whitespace is not inserted prior to the first item or subsequent to the last item. Unless otherwise specified, an empty list is serialized as the empty string.

3. CSSOMString

Most strings in CSSOM interfaces use the CSSOMString type. Each implementation chooses to define it as either USVString or DOMString:

typedef USVString CSSOMString;

Or, alternatively:

typedef DOMString CSSOMString;

The difference is only observable from web content when surrogate code units are involved. DOMString would preserve them, whereas USVString would replace them with U+FFFD REPLACEMENT CHARACTER.

This choice effectively allows implementations to do this replacement, but does not require it.

Using USVString enables an implementation to use UTF-8 internally to represent strings in memory. Since well-formed UTF-8 specifically disallows surrogate code points, it effectively requires this replacement.

On the other hand, implementations that internally represent strings as 16-bit code units might prefer to avoid the cost of doing this replacement.

4. Media Queries

Media queries are defined by [MEDIAQUERIES]. This section defines various concepts around media queries, including their API and serialization form.

4.1. Parsing Media Queries

To parse a media query list for a given string s into a media query list is defined in the Media Queries specification. Return the list of media queries that the algorithm defined there gives.

Note: A media query that ends up being "ignored" will turn into "not all".

To parse a media query for a given string s means to follow the parse a media query list steps and return null if more than one media query is returned or a media query if a single media query is returned.

Note: Again, a media query that ends up being "ignored" will turn into "not all".

4.2. Serializing Media Queries

To serialize a media query list run these steps:

If the media query list is empty, then return the empty string.
Serialize each media query in the list of media queries, in the same order as they appear in the media query list, and then serialize the list.

To serialize a media query let s be the empty string, run the steps below:

If the media query is negated append "not", followed by a single SPACE (U+0020), to s.
Let type be the serialization as an identifier of the media type of the media query, converted to ASCII lowercase.
If the media query does not contain media features append type, to s, then return s.
If type is not "all" or if the media query is negated append type, followed by a single SPACE (U+0020), followed by "and", followed by a single SPACE (U+0020), to s.
Then, for each media feature:
1. Append a "(" (U+0028), followed by the media feature name, converted to ASCII lowercase, to s.
2. If a value is given append a ":" (U+003A), followed by a single SPACE (U+0020), followed by the serialized media feature value, to s.
3. Append a ")" (U+0029) to s.
4. If this is not the last media feature append a single SPACE (U+0020), followed by "and", followed by a single SPACE (U+0020), to s.
Return s.