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-LEVEL-2-STYLE]. 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#supported-styling-languageReferenced in:5.3.1. Fetching CSS style sheets (2)5.3.4. Requirements on User Agents Implementing the xml-stylesheet processing instruction 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#supported-css-propertyReferenced in:2. Terminology5.6.1. The CSSStyleDeclaration Interface (2) (3) (4) (5) (6)6.2. Extensions to the Window Interface refers to a CSS property that the user agent implements, and that is defined to be a case-insensitive property in the CSS specification. A supported CSS property must be in its lowercase form for the purpose of comparisons 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#escape-a-characterReferenced in:2.1. Common Serializing Idioms (2) (3) means to create a string of "\" (U+005C), followed by the character.

To escape a character as code point#escape-a-character-as-code-pointReferenced in:2.1. Common Serializing Idioms (2) (3) (4) (5) 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#serialize-an-identifierReferenced in:3.2. Serializing Media Queries4.2. Serializing Selectors (2) (3) (4) (5) (6)5.4. CSS Rules5.7.2. Serializing CSS Values7.1. The CSS.escape() Method 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 string#serialize-a-stringReferenced in:2.1. Common Serializing Idioms4.2. Serializing Selectors (2)5.7.2. Serializing CSS Values 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) escaped as code point.
• 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#serialize-a-urlReferenced in:5.4. CSS Rules (2)5.7.2. Serializing CSS Values means to create a string represented by "url(", followed by the string escaped value of the given string, followed by ")".

To serialize a comma-separated list#serialize-a-comma-separated-listReferenced in:3.2. Serializing Media Queries4.2. Serializing Selectors5.7.2. Serializing CSS Values (2) (3) 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#serialize-a-whitespace-separated-listReferenced in:5.7.2. Serializing CSS Values 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. Media Queries

Media queries are defined by the Media Queries specification. This section defines various concepts around media queries, including their API and serialization form.

3.1. Parsing Media Queries

To parse a media query list#parse-a-media-query-listReferenced in:3.1. Parsing Media Queries3.4. The MediaList Interface for a given string s into a media query list is defined in the Media Queries specification. Return the list of one or more 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#parse-a-media-queryReferenced in:3.4. The MediaList Interface (2) 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".

3.2. Serializing Media Queries

To serialize a media query list#serialize-a-media-query-listReferenced in:3.4. The MediaList Interface5.4. CSS Rules run these steps:

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

To serialize a media query#serialize-a-media-queryReferenced in:3.2. Serializing Media Queries3.3. Comparing Media Queries let s be the empty string, run the steps below, and finally return s:

1. If the media query is negated append "not", followed by a single SPACE (U+0020), to s.
2. Let type be the media type of the media query, escaped and converted to ASCII lowercase.
3. If the media query does not contain media features append type, to s, then return s and terminate this algorithm.
4. 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.
5. Sort the media features in lexicographical order.
6. 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.

not screen and (min-WIDTH:5px) AND (max-width:40px)

not screen and (max-width: 40px) and (min-width: 5px)

all and (color) and (color)

(color)

3.2.1. Serializing Media Feature Values

This should probably be done in terms of mapping it to serializing CSS values as media features are defined in terms of CSS values after all.

To serialize a media feature value#serialize-a-media-feature-valueReferenced in:3.2. Serializing Media Queries named v locate v in the first column of the table below and use the serialization format described in the second column:

Other specifications can extend this table and vendor-prefixed media features can have custom serialization formats as well.

3.3. Comparing Media Queries

To compare media queries#compare-media-queriesReferenced in:3.4. The MediaList Interface (2) m1 and m2 means to serialize them both and return true if they are a case-sensitive match and false if they are not.

3.4. The MediaList Interface

An object that implements the MediaList interface has an associated collection of media queries#medialist-collection-of-media-queriesReferenced in:3.4. The MediaList Interface (2) (3) (4) (5) (6) (7) (8) (9) (10).

[ArrayClass]
interface MediaList#medialistReferenced in:3.4. The MediaList Interface5.1. CSS Style Sheets5.1.1. The StyleSheet Interface5.4.4. The CSSImportRule Interface5.4.6. The CSSMediaRule Interface {
  [TreatNullAs=EmptyString] stringifier attribute DOMString mediaText;
  readonly attribute unsigned long length;
  getter DOMString? item(unsigned long index);
  void appendMedium(DOMString medium);
  void deleteMedium(DOMString medium);
};

The object’s supported property indices are the numbers in the range zero to one less than the number of media queries in the collection of media queries represented by the collection. If there are no such media queries, then there are no supported property indices.

To create a MediaList object#create-a-medialist-objectReferenced in:5.1. CSS Style Sheets (2) with a string text, run the following steps:

1. Create a new MediaList object.
2. Set its mediaText attribute to text.
3. Return the newly created MediaList object.

The mediaText#dom-medialist-mediatextReferenced in:3.4. The MediaList Interface (2) (3)5.1. CSS Style Sheets (2)5.1.1. The StyleSheet Interface5.4.4. The CSSImportRule Interface5.4.6. The CSSMediaRule Interface attribute, on getting, must return a serialization of the collection of media queries. Setting the mediaText attribute must run these steps:

1. Empty the collection of media queries.
2. If the given value is the empty string terminate these steps.
3. Append all the media queries as a result of parsing the given value to the collection of media queries.

The item(index)#dom-medialist-itemReferenced in:3.4. The MediaList Interface method must return the media query in the collection of media queries given by index, or null, if index is greater than or equal to the number of media queries in the collection of media queries.

The length#dom-medialist-lengthReferenced in:3.4. The MediaList Interface attribute must return the number of media queries in the collection of media queries.

The appendMedium(medium)#dom-medialist-appendmediumReferenced in:3.4. The MediaList Interface method must run these steps:

1. Let m be the result of parsing the given value.
2. If m is null terminate these steps.
3. If comparing m with any of the media queries in the collection of media queries returns true terminate these steps.
4. Append m to the collection of media queries.

The deleteMedium(medium)#dom-medialist-deletemediumReferenced in:3.4. The MediaList Interface method must run these steps:

1. Let m be the result of parsing the given value.
2. If m is null terminate these steps.
3. Remove any media query from the collection of media queries for which comparing the media query with m returns true.

4. Selectors

Selectors are defined in the Selectors specification. This section mainly defines how to serialize them.

4.1. Parsing Selectors

To parse a group of selectors#parse-a-group-of-selectorsReferenced in:5.4.3. The CSSStyleRule Interface means to parse the value using the selectors_group production defined in the Selectors specification and return either a group of selectors if parsing did not fail or null if parsing did fail.

4.2. Serializing Selectors

To serialize a group of selectors#serialize-a-group-of-selectorsReferenced in:4.2. Serializing Selectors5.4. CSS Rules5.4.3. The CSSStyleRule Interface serialize each selector in the group of selectors and then serialize the group.

To serialize a selector#serialize-a-selectorReferenced in:4.2. Serializing Selectors let s be the empty string, run the steps below for each part of the chain of the selector, and finally return s:

1. If there is only one simple selector in the compound selectors which is a universal selector, append the result of serializing the universal selector to s.
2. Otherwise, for each simple selector in the compound selectors that is not a universal selector of which the namespace prefix maps to a namespace that is not the default namespace serialize the simple selector and append the result to s.
3. If this is not the last part of the chain of the selector append a single SPACE (U+0020), followed by the combinator ">", "+", "~", ">>", "||", as appropriate, followed by another single SPACE (U+0020) if the combinator was not whitespace, to s.
4. If this is the last part of the chain of the selector and there is a pseudo-element, append "::" followed by the name of the pseudo-element, to s.

To serialize a simple selector#serialize-a-simple-selectorReferenced in:4.2. Serializing Selectors (2) let s be the empty string, run the steps below, and finally return s:

type selector

universal selector

1. If the namespace prefix maps to a namespace that is not the default namespace and is not the null namespace (not in a namespace) append the escaped namespace prefix, followed by a "|" (U+007C) to s.
2. If the namespace prefix maps to a namespace that is the null namespace (not in a namespace) append "|" (U+007C) to s.
3. If this is a type selector append the escaped element name to s.
4. If this is a universal selector append "*" (U+002A) to s.

attribute selector

1. Append "[" (U+005B) to s.
2. If the namespace prefix maps to a namespace that is not the null namespace (not in a namespace) append the escaped namespace prefix, followed by a "|" (U+007C) to s.
3. Append the escaped attribute name to s.
4. If there is an attribute value specified, append "=", "~=", "|=", "^=", "$=", or "*=" as appropriate (depending on the type of attribute selector), followed by the string escaped attribute value, to s.
5. If the attribute selector has the case-sensitivity flag present, append " i" (U+0020 U+0069) to s.
6. Append "]" (U+005D) to s.

class selector

Append a "." (U+002E), followed by the escaped class name to s.

ID selector

Append a "#" (U+0023), followed by the escaped ID to s.

pseudo-class

If the pseudo-class does not accept arguments append ":" (U+003A), followed by the name of the pseudo-class, to s.

Otherwise, append ":" (U+003A), followed by the name of the pseudo-class, followed by "(" (U+0028), followed by the value of the pseudo-class argument(s) determined as per below, followed by ")" (U+0029), to s.

:lang()

The value of each argument string escaped, preserving relative order, separated by ", " (U+002C U+0020).

:nth-child()

:nth-last-child()

:nth-of-type()

:nth-last-of-type()

The result of serializing the value using the rules to serialize an <an+b> value.

:not()

The result of serializing the value using the rules for serializing a group of selectors.

5. CSS

5.1. CSS Style Sheets

A CSS style sheet#css-style-sheetReferenced in:5.1. CSS Style Sheets (2) (3) (4) (5) (6) (7) (8) (9) (10) (11) (12) (13) (14)5.1.2. The CSSStyleSheet Interface5.2. CSS Style Sheet Collections (2) (3) (4) (5) (6) (7) (8) (9) (10) (11) (12) (13) (14) (15)5.2.2. The StyleSheetList Interface (2) (3) (4) (5)5.3. Style Sheet Association5.3.2. The LinkStyle Interface5.3.3. Requirements on specifications5.4. CSS Rules5.4.4. The CSSImportRule Interface (2) (3) (4)6.2. Extensions to the Window Interface is an abstract concept that represents a style sheet as defined by the CSS specification. In the CSSOM a CSS style sheet is represented as a CSSStyleSheet object. A CSS style sheet has a number of associated state items:

type#concept-css-style-sheet-typeReferenced in:5.1.1. The StyleSheet Interface

The literal string "text/css".

location#concept-css-style-sheet-locationReferenced in:5.1.1. The StyleSheet Interface5.3.4. Requirements on User Agents Implementing the xml-stylesheet processing instruction5.3.5. Requirements on User Agents Implementing the HTTP Link Header

Specified when created. The absolute URL of the first request of the CSS style sheet or null if the CSS style sheet was embedded. Does not change during the lifetime of the CSS style sheet.

parent CSS style sheet#concept-css-style-sheet-parent-css-style-sheetReferenced in:5.1. CSS Style Sheets5.1.1. The StyleSheet Interface5.2. CSS Style Sheet Collections5.3.4. Requirements on User Agents Implementing the xml-stylesheet processing instruction5.3.5. Requirements on User Agents Implementing the HTTP Link Header

Specified when created. The CSS style sheet that is the parent of the CSS style sheet or null if there is no associated parent.

owner node#concept-css-style-sheet-owner-nodeReferenced in:5.1. CSS Style Sheets (2) (3)5.1.1. The StyleSheet Interface5.2. CSS Style Sheet Collections5.3. Style Sheet Association5.3.2. The LinkStyle Interface5.3.4. Requirements on User Agents Implementing the xml-stylesheet processing instruction5.3.5. Requirements on User Agents Implementing the HTTP Link Header

Specified when created. The DOM node associated with the CSS style sheet or null if there is no associated DOM node.

owner CSS rule#concept-css-style-sheet-owner-css-ruleReferenced in:5.1.2. The CSSStyleSheet Interface5.2. CSS Style Sheet Collections5.3.4. Requirements on User Agents Implementing the xml-stylesheet processing instruction5.3.5. Requirements on User Agents Implementing the HTTP Link Header

Specified when created. The CSS rule in the parent CSS style sheet that caused the inclusion of the CSS style sheet or null if there is no associated rule.

media#concept-css-style-sheet-mediaReferenced in:5.1. CSS Style Sheets (2) (3) (4)5.1.1. The StyleSheet Interface5.3.4. Requirements on User Agents Implementing the xml-stylesheet processing instruction5.3.5. Requirements on User Agents Implementing the HTTP Link Header

Specified when created. The MediaList object associated with the CSS style sheet.

If this property is specified to a string, the media must be set to the return value of invoking create a MediaList object steps for that string.

If this property is specified to an attribute of the owner node, the media must be set to the return value of invoking create a MediaList object steps for the value of that attribute. Whenever the attribute is set, changed or removed, the media’s mediaText attribute must be set to the new value of the attribute, or to null if the attribute is absent.

Note: Changing the media’s mediaText attribute does not change the corresponding attribute on the owner node.

title#concept-css-style-sheet-titleReferenced in:5.1. CSS Style Sheets (2) (3)5.1.1. The StyleSheet Interface (2)5.2. CSS Style Sheet Collections (2) (3) (4) (5) (6) (7) (8)5.3.4. Requirements on User Agents Implementing the xml-stylesheet processing instruction5.3.5. Requirements on User Agents Implementing the HTTP Link Header

Specified when created. The title of the CSS style sheet, which can be the empty string.

In the following, the title is non-empty for the first style sheet, but is empty for the second and third style sheets.

<style title="papaya whip">
  body { background: #ffefd5; }
</style>

<style title="">
  body { background: orange; }
</style>

<style>
  body { background: brown; }
</style>

If this property is specified to an attribute of the owner node, the title must be set to the value of that attribute. Whenever the attribute is set, changed or removed, the title must be set to the new value of the attribute, or to the empty string if the attribute is absent.

alternate flag#concept-css-style-sheet-alternate-flagReferenced in:5.1. CSS Style Sheets5.2. CSS Style Sheet Collections (2)5.3.4. Requirements on User Agents Implementing the xml-stylesheet processing instruction5.3.5. Requirements on User Agents Implementing the HTTP Link Header

Specified when created. Either set or unset. Unset by default.

The following CSS style sheets have their alternate flag set:

<?xml-stylesheet alternate="yes" title="x" href="data:text/css,…"?>

<link rel="alternate stylesheet" title="x" href="data:text/css,…">

disabled flag#concept-css-style-sheet-disabled-flagReferenced in:5.1.1. The StyleSheet Interface (2) (3)5.2. CSS Style Sheet Collections (2) (3) (4) (5) (6) (7) (8)

Either set or unset. Unset by default.

Note: Even when unset it does not necessarily mean that the CSS style sheet is actually used for rendering.

CSS rules#concept-css-style-sheet-css-rulesReferenced in:5.1. CSS Style Sheets5.1.2. The CSSStyleSheet Interface (2) (3)5.4.4. The CSSImportRule Interface

The CSS rules associated with the CSS style sheet.

origin-clean flag#concept-css-style-sheet-origin-clean-flagReferenced in:5.1.2. The CSSStyleSheet Interface (2) (3)5.2. CSS Style Sheet Collections5.3.4. Requirements on User Agents Implementing the xml-stylesheet processing instruction5.3.5. Requirements on User Agents Implementing the HTTP Link Header6.2. Extensions to the Window Interface

Specified when created. Either set or unset. If it is set, the API allows reading and modifying of the CSS rules.

5.1.1. The StyleSheet Interface

The StyleSheet interface represents an abstract, base style sheet.

interface StyleSheet#stylesheetReferenced in:5.1.1. The StyleSheet Interface (2) (3)5.1.2. The CSSStyleSheet Interface5.2.2. The StyleSheetList Interface5.3.2. The LinkStyle Interface (2) {
  readonly attribute DOMString type;
  readonly attribute DOMString? href;
  readonly attribute (Element or ProcessingInstruction)? ownerNode;
  readonly attribute StyleSheet? parentStyleSheet;
  readonly attribute DOMString? title;
  [SameObject, PutForwards=mediaText] readonly attribute MediaList media;
  attribute boolean disabled;
};

The type#dom-stylesheet-typeReferenced in:5.1.1. The StyleSheet Interface attribute must return the type.

The href#dom-stylesheet-hrefReferenced in:5.1.1. The StyleSheet Interface5.4.4. The CSSImportRule Interface attribute must return the location.

The ownerNode#dom-stylesheet-ownernodeReferenced in:5.1.1. The StyleSheet Interface attribute must return the owner node.

The parentStyleSheet#dom-stylesheet-parentstylesheetReferenced in:5.1.1. The StyleSheet Interface attribute must return the parent CSS style sheet.

The title#dom-stylesheet-titleReferenced in:5.1.1. The StyleSheet Interface attribute must return the title or null if title is the empty string.

The media#dom-stylesheet-mediaReferenced in:5.1.1. The StyleSheet Interface5.4.4. The CSSImportRule Interface attribute must return the media.

The disabled#dom-stylesheet-disabledReferenced in:5.1.1. The StyleSheet Interface (2) attribute, on getting, must return true if the disabled flag is set, or false otherwise. On setting, the disabled attribute must set the disabled flag if the new value is true, or unset the disabled flag otherwise.

5.1.2. The CSSStyleSheet Interface

The CSSStyleSheet interface represents a CSS style sheet.

interface CSSStyleSheet#cssstylesheetReferenced in:5.1. CSS Style Sheets5.1.2. The CSSStyleSheet Interface (2)5.4.2. The CSSRule Interface5.4.4. The CSSImportRule Interface : StyleSheet {
  readonly attribute CSSRule? ownerRule;
  [SameObject] readonly attribute CSSRuleList cssRules;
  unsigned long insertRule(DOMString rule, unsigned long index);
  void deleteRule(unsigned long index);
};

The ownerRule#dom-cssstylesheet-ownerruleReferenced in:5.1.2. The CSSStyleSheet Interface attribute must return the owner CSS rule. If a value other than null is ever returned, then that same value must always be returned on each get access.

The cssRules#dom-cssstylesheet-cssrulesReferenced in:5.1.2. The CSSStyleSheet Interface attribute must follow these steps:

1. If the origin-clean flag is unset, throw a SecurityError exception.
2. Return a read-only, live CSSRuleList object representing the CSS rules.

   Note: Even though the returned CSSRuleList object is read-only (from the perspective of client-authored script), it can nevertheless change over time due to its liveness status. For example, invoking the insertRule() or deleteRule() methods can result in mutations reflected in the returned object.

The insertRule(rule, index)#dom-cssstylesheet-insertruleReferenced in:5.1.2. The CSSStyleSheet Interface (2)10.1. Changes From 5 December 2013 method must run the following steps:

1. If the origin-clean flag is unset, throw a SecurityError exception.
2. Return the result of invoking insert a CSS rule rule in the CSS rules at index.

The deleteRule(index)#dom-cssstylesheet-deleteruleReferenced in:5.1.2. The CSSStyleSheet Interface (2) method must run the following steps:

1. If the origin-clean flag is unset, throw a SecurityError exception.
2. Remove a CSS rule in the CSS rules at index.

5.2. CSS Style Sheet Collections

Below various new concepts are defined that are associated with each Document object.

Each Document has an associated list of zero or more CSS style sheets, named the document CSS style sheets#document-css-style-sheetsReferenced in:5.2. CSS Style Sheet Collections (2) (3) (4)5.2.3. Extensions to the Document Interface5.3.2. The LinkStyle Interface. This is an ordered list that contains all CSS style sheets associated with the Document, in tree order, with CSS style sheets created from HTTP Link headers first, if any, in header order.

To create a CSS style sheet#create-a-css-style-sheetReferenced in:5.3.3. Requirements on specifications5.3.4. Requirements on User Agents Implementing the xml-stylesheet processing instruction5.3.5. Requirements on User Agents Implementing the HTTP Link Header, run these steps:

1. Create a new CSS style sheet object and set its properties as specified.
2. Then run the add a CSS style sheet steps for the newly created CSS style sheet.

   If the origin-clean flag is unset, this can expose information from the user’s intranet.

To add a CSS style sheet#add-a-css-style-sheetReferenced in:5.2. CSS Style Sheet Collections, run these steps:

1. Add the CSS style sheet to the list of document CSS style sheets at the appropriate location. The remainder of these steps deal with the disabled flag.
2. If the disabled flag is set, terminate these steps.
3. If the title is not the empty string, the alternate flag is unset, and preferred CSS style sheet set name is the empty string change the preferred CSS style sheet set name to the title.
4. If any of the following is true unset the disabled flag and terminate these steps:
   • The title is the empty string.
   • The last CSS style sheet set name is null and the title is a case-sensitive match for the preferred CSS style sheet set name.
   • The title is a case-sensitive match for the last CSS style sheet set name.
5. Set the disabled flag.

To remove a CSS style sheet#remove-a-css-style-sheetReferenced in:5.3.4. Requirements on User Agents Implementing the xml-stylesheet processing instruction, run these steps:

1. Remove the CSS style sheet from the list of document CSS style sheets.
2. Set the CSS style sheet’s parent CSS style sheet, owner node and owner CSS rule to null.

A persistent CSS style sheet is a CSS style sheet from the document CSS style sheets whose title is the empty string and whose alternate flag is unset.

A CSS style sheet set#css-style-sheet-setReferenced in:5.2. CSS Style Sheet Collections (2) (3) (4) (5) (6)5.2.1. The HTTP Default-Style Header is an ordered collection of one or more CSS style sheets from the document CSS style sheets which have an identical title that is not the empty string.

A CSS style sheet set name#css-style-sheet-set-nameReferenced in:5.2. CSS Style Sheet Collections is the title the CSS style sheet set has in common.

An enabled CSS style sheet set#enabled-css-style-sheet-setReferenced in:5.2.1. The HTTP Default-Style Header is a CSS style sheet set of which each CSS style sheet has its disabled flag unset.

To enable a CSS style sheet set#enable-a-css-style-sheet-setReferenced in:5.2. CSS Style Sheet Collections (2) with name name, run these steps:

1. If name is the empty string, set the disabled flag for each CSS style sheet that is in a CSS style sheet set and terminate these steps.
2. Unset the disabled flag for each CSS style sheet in a CSS style sheet set whose CSS style sheet set name is a case-sensitive match for name and set it for all other CSS style sheets in a CSS style sheet set.

To select a CSS style sheet set#select-a-css-style-sheet-setReferenced in:5.2. CSS Style Sheet Collections with name name, run these steps:

1. enable a CSS style sheet set with name name.
2. Set last CSS style sheet set name to name.

A last CSS style sheet set name#last-css-style-sheet-set-nameReferenced in:5.2. CSS Style Sheet Collections (2) (3) (4) is a concept to determine what CSS style sheet set was last selected. Initially its value is null.

A preferred CSS style sheet set name#preferred-css-style-sheet-set-nameReferenced in:5.2. CSS Style Sheet Collections (2) (3) (4)5.2.1. The HTTP Default-Style Header is a concept to determine which CSS style sheets need to have their disabled flag unset. Initially its value is the empty string.

To change the preferred CSS style sheet set name#change-the-preferred-css-style-sheet-set-nameReferenced in:5.2. CSS Style Sheet Collections5.2.1. The HTTP Default-Style Header with name name, run these steps:

1. Let current be the preferred CSS style sheet set name.
2. Set preferred CSS style sheet set name to name.
3. If name is not a case-sensitive match for current and last CSS style sheet set name is null enable a CSS style sheet set with name name.

5.2.1. The HTTP Default-Style Header

The HTTP Default-Style header can be used to set the preferred CSS style sheet set name influencing which CSS style sheet set is (initially) the enabled CSS style sheet set.

For each HTTP Default-Style header, in header order, the user agent must change the preferred CSS style sheet set name with name being the value of the header.

5.2.2. The StyleSheetList Interface

The StyleSheetList interface represents an ordered collection of CSS style sheets.

[ArrayClass]
interface StyleSheetList#stylesheetlistReferenced in:5.2.2. The StyleSheetList Interface (2)5.2.3. Extensions to the Document Interface (2) {
  getter StyleSheet? item(unsigned long index);
  readonly attribute unsigned long length;
};

The object’s supported property indices are the numbers in the range zero to one less than the number of CSS style sheets represented by the collection. If there are no such CSS style sheets, then there are no supported property indices.

The item(index)#dom-stylesheetlist-itemReferenced in:5.2.2. The StyleSheetList Interface method must return the indexth CSS style sheet in the collection. If there is no indexth object in the collection, then the method must return null.

The length#dom-stylesheetlist-lengthReferenced in:5.2.2. The StyleSheetList Interface attribute must return the number of CSS style sheets represented by the collection.

5.2.3. Extensions to the Document Interface

partial interface Document {
  [SameObject] readonly attribute StyleSheetList styleSheets;
};

The styleSheets#dom-document-stylesheetsReferenced in:5.2.3. Extensions to the Document Interface attribute must return a StyleSheetList collection representing the document CSS style sheets.

5.3. Style Sheet Association

This section defines the interface an owner node of a CSS style sheet has to implement and defines the requirements for xml-stylesheet processing instructions and HTTP Link headers when the link relation type is an ASCII case-insensitive match for "stylesheet".

5.3.1. Fetching CSS style sheets

To fetch a CSS style sheet#fetch-a-css-style-sheetReferenced in:5.3.4. Requirements on User Agents Implementing the xml-stylesheet processing instruction5.3.5. Requirements on User Agents Implementing the HTTP Link Header with parsed URL parsed URL, referrer referrer, document document, optionally a set of parameters parameters (used as input to creating a request), follow these steps:

1. Let origin be document’s origin.
2. Let request be a new request, with the url parsed URL, origin origin, referrer referrer, and if specified the set of parameters parameters.
3. Let response be the result of fetching request.
4. Wait until response is available.
5. If response is a network error, return an error.
6. If document is in quirks mode, response is CORS-same-origin and the Content-Type metadata of response is not a supported styling language change the Content-Type metadata of response to text/css.
7. If response is not in a supported styling language return an error.
8. Return response.

5.3.2. The LinkStyle Interface

The associated CSS style sheet#associated-css-style-sheetReferenced in:5.3.2. The LinkStyle Interface (2)5.3.4. Requirements on User Agents Implementing the xml-stylesheet processing instruction of a node is the CSS style sheet in the list of document CSS style sheets of which the owner node implements the LinkStyle interface.

[NoInterfaceObject]
interface LinkStyle#linkstyleReferenced in:5.3.2. The LinkStyle Interface (2)5.3.3. Requirements on specifications5.3.4. Requirements on User Agents Implementing the xml-stylesheet processing instruction {
  readonly attribute StyleSheet? sheet;
};

The sheet#dom-linkstyle-sheetReferenced in:5.3.2. The LinkStyle Interface (2) (3) attribute must return the associated CSS style sheet for the node or null if there is no associated CSS style sheet.

<style type="text/css">
  body { background:lime }
</style>

<style type="text/example-sheets">
  $(body).background := lime
</style>

Note: Whether or not the node refers to a style sheet is defined by the specification that defines the semantics of said node.

5.3.3. Requirements on specifications

Specifications introducing new ways of associating style sheets through the DOM should define which nodes implement the LinkStyle interface. When doing so, they must also define when a CSS style sheet is created.

5.3.4. Requirements on User Agents Implementing the xml-stylesheet processing instruction

ProcessingInstruction implements LinkStyle;

The prolog#prologReferenced in:5.3.4. Requirements on User Agents Implementing the xml-stylesheet processing instruction (2) refers to nodes that are children of the document and are not following the Element child of the document, if any.

When a ProcessingInstruction node node becomes part of the prolog, is no longer part of the prolog, or has its data changed, these steps must be run:

1. If an instance of this algorithm is currently running for node, abort that instance, and stop the associated fetching if applicable.
2. If node has an associated CSS style sheet, remove it.
3. If node is not an xml-stylesheet processing instruction, terminate these steps.
4. If node does not have an href pseudo-attribute, terminate these steps.
5. Let title be the value of the title pseudo-attribute or the empty string if the title pseudo-attribute is not specified.
6. If there is an alternate pseudo-attribute whose value is a case-sensitive match for "yes" and title is the empty string terminate these steps.
7. If there is a type pseudo-attribute whose value is not a supported styling language the user agent may terminate these steps.
8. Let input URL be the value specified by the href pseudo-attribute.
9. Let document be node’s node document
10. Let base URL be document’s document base URL.
11. Let referrer be document’s address.
12. Let parsed URL be the return value of invoking the URL parser with the string input URL and the base URL base URL.
13. If parsed URL is failure, terminate these steps.
14. Let response be the result of fetching a CSS style sheet with parsed URL parsed URL, referrer referrer and document document.
15. If response is an error, terminate these steps.
16. Create a CSS style sheet with the following properties:

    location

    The result of invoking the URL serializer with parsed URL.

    parent CSS style sheet

    null.

    owner node

    node.

    owner CSS rule

    null.

    media

    The value of the media pseudo-attribute if any, or the empty string otherwise.

    title

    title.

    alternate flag

    Set if the alternate pseudo-attribute value is a case-sensitive match for "yes", or unset otherwise.

    origin-clean flag

    Set if response is CORS-same-origin, or unset otherwise.

    The CSS environment encoding is the result of running the following steps:

    1. If the element has a charset pseudo-attribute, get an encoding from that pseudo-attribute’s value. If that succeeds, return the resulting encoding and abort these steps.
    2. Otherwise, return the document’s character encoding. [DOM]

A style sheet referenced by an xml-stylesheet processing instruction using the rules in this section, in the context of the Document of an XML parser is said to be a style sheet that is blocking scripts if the ProcessingInstruction node was created by that Document's parser, and the style sheet was enabled when the node was created by the parser, and the style sheet ready flag is not yet set, and, the last time the event loop reached step 1, the node was in that Document, and the user agent hasn’t given up on that particular style sheet yet. A user agent may give up on such a style sheet at any time.

5.3.5. Requirements on User Agents Implementing the HTTP Link Header

For each HTTP Link header of which one of the link relation types is an ASCII case-insensitive match for "stylesheet" these steps must be run:

1. Let title be the value of the first of all the title parameters. If there are no such parameters it is the empty string.
2. If one of the (other) link relation types is an ASCII case-insensitive match for "alternate" and title is the empty string terminate these steps.
3. Let input URL be the value specified.

   Be more specific

4. Let base URL be the document’s document base URL.

   Is there a document at this point?

5. Let referrer be the document’s address.
6. Let origin be the document’s origin.
7. Let parsed URL be the return value of invoking the URL parser with the string input URL and the base URL base URL.
8. If parsed URL is failure, terminate these steps.
9. Let response be the result of fetching a CSS style sheet with parsed URL parsed URL, referrer referrer and document being the document.

   What if the HTML parser hasn’t decided on quirks/non-quirks yet?

10. Create a CSS style sheet with the following properties:

    location

    The result of invoking the URL serializer with parsed URL.

    owner node

    null.

    parent CSS style sheet

    null.

    owner CSS rule

    null.

    media

    The value of the first media parameter.

    title

    title.

    alternate flag

    Set if one of the specified link relation type for this HTTP Link header is an ASCII case-insensitive match for "alternate", or false otherwise.

    origin-clean flag

    Set if response is CORS-same-origin, or unset otherwise.

A style sheet referenced by a HTTP Link header using the rules in this section is said to be a style sheet that is blocking scripts if the style sheet was enabled when created, and the style sheet ready flag is not yet set, and the user agent hasn’t given up on that particular style sheet yet. A user agent may give up on such a style sheet at any time.

5.4. CSS Rules

A CSS rule#css-ruleReferenced in:5.1. CSS Style Sheets5.4. CSS Rules (2) (3) (4) (5)5.4.2. The CSSRule Interface5.6. CSS Declaration Blocks is an abstract concept that denotes a rule as defined by the CSS specification. A CSS rule is represented as an object that implements a subclass of the CSSRule interface, and which has the following associated state items:

type#concept-css-rule-typeReferenced in:5.4. CSS Rules (2)

A non-negative integer associated with a particular type of rule. This item is initialized when a rule is created and cannot change.

text

A text representation of the rule suitable for direct use in a style sheet. This item is initialized when a rule is created and can be changed.

parent CSS rule#concept-css-rule-parent-css-ruleReferenced in:5.4. CSS Rules5.4.2. The CSSRule Interface

A reference to an enclosing CSS rule or null. If the rule has an enclosing rule when it is created, then this item is initialized to the enclosing rule; otherwise it is null. It can be changed to null.

parent CSS style sheet#concept-css-rule-parent-css-style-sheetReferenced in:5.4. CSS Rules5.4.2. The CSSRule Interface

A reference to a parent CSS style sheet or null. This item is initialized to reference an associated style sheet when the rule is created. It can be changed to null.

child CSS rules#concept-css-rule-child-css-rulesReferenced in:5.4.5. The CSSGroupingRule Interface (2) (3)

A list of child CSS rules. The list can be mutated.

In addition to the above state, each CSS rule may be associated with other state in accordance with its type.

To parse a CSS rule#parse-a-css-ruleReferenced in:5.4. CSS Rules from a string string, run the following steps:

1. Let rule be the return value of invoking parse a rule with string.
2. If rule is a syntax error, return rule.
3. Let parsed rule be the result of parsing rule according to the appropriate CSS specifications, dropping parts that are said to be ignored. If the whole style rule is dropped, return a syntax error.
4. Return parsed rule.

To serialize a CSS rule#serialize-a-css-ruleReferenced in:5.4.2. The CSSRule Interface, perform one of the following in accordance with the CSS rule’s type:

CSSStyleRule

The result of concatenating the following:

1. The result of performing serialize a group of selectors on the rule’s associated selectors.
2. The string " { ", i.e., a single SPACE (U+0020), followed by LEFT CURLY BRACKET (U+007B), followed by a single SPACE (U+0020).
3. The result of performing serialize a CSS declaration block on the rule’s associated declarations.
4. If the rule is associated with one or more declarations, the string " ", i.e., a single SPACE (U+0020).
5. The string "}", RIGHT CURLY BRACKET (U+007D).

CSSImportRule

The result of concatenating the following:

1. The string "@import" followed by a single SPACE (U+0020).
2. The result of performing serialize a URL on the rule’s location.
3. If the rule’s associated media list is not empty, a single SPACE (U+0020) followed by the result of performing serialize a media query list on the media list.
4. The string ";", i.e., SEMICOLON (U+003B).

@import url("import.css");

@import url("print.css") print;

CSSMediaRule

Issue: ...

CSSFontFaceRule

Issue: ...

CSSPageRule

Issue: ...

CSSNamespaceRule

The literal string "@namespace", followed by a single SPACE (U+0020), followed by the identifier escaped value of the prefix attribute (if any), followed by a single SPACE (U+0020) if there is a prefix, followed by the URL escaped value of the namespaceURI attribute, followed the character ";" (U+003B).

To insert a CSS rule#insert-a-css-ruleReferenced in:5.1.2. The CSSStyleSheet Interface5.4.5. The CSSGroupingRule Interface rule in a CSS rule list list at index index, follow these steps:

1. Set new rule to the results of performing parse a CSS rule on argument rule.
2. If new rule is a syntax error, throw a SyntaxError exception.
3. Set length to the number of items in list.
4. If index is greater than length, then throw an IndexSizeError exception.
5. If new rule cannot be inserted into list at the zero-index position index due to constraints specified by CSS, then throw a HierarchyRequestError exception. [CSS21]

   Note: For example, a CSS style sheet cannot contain an @import at-rule after a style rule.

6. If new rule is an @namespace at-rule, and list contains anything other than @import at-rules, and @namespace at-rules, throw an InvalidStateError exception.
7. Insert new rule into list at the zero-indexed position index.
8. Return index.

To remove a CSS rule#remove-a-css-ruleReferenced in:5.1.2. The CSSStyleSheet Interface5.4.2. The CSSRule Interface5.4.5. The CSSGroupingRule Interface from a CSS rule list list at index index, follow these steps:

1. Set length to the number of items in list.
2. If index is greater than or equal to length, then throw an IndexSizeError exception.
3. Set old rule to the indexth item in list.
4. If old rule is an @namespace at-rule, and list contains anything other than @import at-rules, and @namespace at-rules, throw an InvalidStateError exception.
5. Remove rule old rule from list at the zero-indexed position index.
6. Set old rule’s parent CSS rule and parent CSS style sheet to null.

5.4.1. The CSSRuleList Interface

The CSSRuleList interface represents an ordered collection of CSS style rules.

[ArrayClass]
interface CSSRuleList#cssrulelistReferenced in:5.1.2. The CSSStyleSheet Interface (2) (3)5.4.1. The CSSRuleList Interface (2)5.4.5. The CSSGroupingRule Interface {
  getter CSSRule? item(unsigned long index);
  readonly attribute unsigned long length;
};

The object’s supported property indices are the numbers in the range zero to one less than the number of CSSRule objects represented by the collection. If there are no such CSSRule objects, then there are no supported property indices.

The item(index)#dom-cssrulelist-itemReferenced in:5.4.1. The CSSRuleList Interface method must return the indexth CSSRule object in the collection. If there is no indexth object in the collection, then the method must return null.

The length#dom-cssrulelist-lengthReferenced in:5.4.1. The CSSRuleList Interface attribute must return the number of CSSRule objects represented by the collection.

5.4.2. The CSSRule Interface

The CSSRule interface represents an abstract, base CSS style rule. Each distinct CSS style rule type is represented by a distinct interface that inherits from this interface.

interface CSSRule#cssruleReferenced in:5.1.2. The CSSStyleSheet Interface5.4. CSS Rules5.4.1. The CSSRuleList Interface (2) (3) (4) (5)5.4.2. The CSSRule Interface (2) (3)5.4.3. The CSSStyleRule Interface5.4.4. The CSSImportRule Interface5.4.5. The CSSGroupingRule Interface5.4.8. The CSSMarginRule Interface5.4.9. The CSSNamespaceRule Interface5.6.1. The CSSStyleDeclaration Interface10.1. Changes From 5 December 2013 {
  const unsigned short STYLE_RULE = 1;
  const unsigned short CHARSET_RULE = 2; // historical
  const unsigned short IMPORT_RULE = 3;
  const unsigned short MEDIA_RULE = 4;
  const unsigned short FONT_FACE_RULE = 5;
  const unsigned short PAGE_RULE = 6;
  const unsigned short MARGIN_RULE = 9;
  const unsigned short NAMESPACE_RULE = 10;
  readonly attribute unsigned short type;
  attribute DOMString cssText;
  readonly attribute CSSRule? parentRule;
  readonly attribute CSSStyleSheet? parentStyleSheet;
};

The type#dom-cssrule-typeReferenced in:5.4.2. The CSSRule Interface attribute must return the CSS rule type, as follows:

If the object is a CSSStyleRule

Return STYLE_RULE#dom-cssrule-style_ruleReferenced in:5.4.2. The CSSRule Interface (numeric value 1).

If the object is a CSSImportRule

Return IMPORT_RULE#dom-cssrule-import_ruleReferenced in:5.4.2. The CSSRule Interface (numeric value 3).

If the object is a CSSMediaRule

Return MEDIA_RULE#dom-cssrule-media_ruleReferenced in:5.4.2. The CSSRule Interface (numeric value 4).

If the object is a CSSFontFaceRule

Return FONT_FACE_RULE#dom-cssrule-font_face_ruleReferenced in:5.4.2. The CSSRule Interface (numeric value 5).

If the object is a CSSPageRule

Return PAGE_RULE#dom-cssrule-page_ruleReferenced in:5.4.2. The CSSRule Interface (numeric value 6).

If the object is a CSSMarginRule

Return MARGIN_RULE#dom-cssrule-margin_ruleReferenced in:5.4.2. The CSSRule Interface (numeric value 9).

If the object is a CSSNamespaceRule

Return NAMESPACE_RULE#dom-cssrule-namespace_ruleReferenced in:5.4.2. The CSSRule Interface (numeric value 10).

Otherwise

Return a value defined on the CSSOM Constants wiki page.

Note: The value 0, formerly known as UNKNOWN_RULE, is made obsolete by this specification. This value will not be re-allocated in the future and will remain reserved.

The cssText#dom-cssrule-csstextReferenced in:5.4.2. The CSSRule Interface (2)10.1. Changes From 5 December 2013 attribute must return a serialization of the CSS rule. On setting the cssText attribute must do nothing.

The parentRule#dom-cssrule-parentruleReferenced in:5.4.2. The CSSRule Interface (2) (3) attribute must return the parent CSS rule.

Note: For example, @media can enclose a rule, in which case parentRule would be non-null; in cases where there is no enclosing rule, parentRule will be null.

The parentStyleSheet#dom-cssrule-parentstylesheetReferenced in:5.4.2. The CSSRule Interface attribute must return the parent CSS style sheet.

Note: The only circumstance where null is returned when a rule has been removed.

Note: Removing a Node that implements the LinkStyle interface from a Document instance does not (by itself) cause the CSSStyleSheet referenced by a CSSRule to be unreachable.

5.4.3. The CSSStyleRule Interface

The CSSStyleRule interface represents a style rule.

interface CSSStyleRule#cssstyleruleReferenced in:5.4. CSS Rules5.4.2. The CSSRule Interface5.4.3. The CSSStyleRule Interface : CSSRule {
  attribute DOMString selectorText;
  [SameObject, PutForwards=cssText] readonly attribute CSSStyleDeclaration style;
};

The selectorText#dom-cssstylerule-selectortextReferenced in:5.4.3. The CSSStyleRule Interface (2) attribute, on getting, must return the result of serializing the associated group of selectors. On setting the selectorText attribute these steps must be run:

1. Run the parse a group of selectors algorithm on the given value.
2. If the algorithm returns a non-null value replace the associated group of selectors with the returned value.
3. Otherwise, if the algorithm returns a null value, do nothing.

The style#dom-cssstylerule-styleReferenced in:5.4.3. The CSSStyleRule Interface attribute must return a CSSStyleDeclaration object for the style rule, with the following properties:

readonly flag

Unset.

declarations

The declared declarations in the rule, in specified order.

parent CSS rule

The context object.

owner node

Null.

The specified order#concept-declarations-specified-orderReferenced in:5.4.3. The CSSStyleRule Interface5.4.7. The CSSPageRule Interface5.4.8. The CSSMarginRule Interface5.6.1. The CSSStyleDeclaration Interface6.1. The ElementCSSInlineStyle Interface for declarations is the same as specified, but with shorthand properties expanded into their longhand properties, in canonical order. If a property is specified more than once (after shorthand expansion), only the one with greatest cascading order must be represented, at the same relative position as it was specified. [CSS3CASCADE]

5.4.4. The CSSImportRule Interface

The CSSImportRule interface represents an @import at-rule.

interface CSSImportRule#cssimportruleReferenced in:5.4. CSS Rules5.4.2. The CSSRule Interface5.4.4. The CSSImportRule Interface : CSSRule {
  readonly attribute DOMString href;
  [SameObject, PutForwards=mediaText] readonly attribute MediaList media;
  [SameObject] readonly attribute CSSStyleSheet styleSheet;
};

The href#dom-cssimportrule-hrefReferenced in:5.4.4. The CSSImportRule Interface attribute must return the URL specified by the @import at-rule.

Note: To get the resolved URL use the href attribute of the associated CSS style sheet.

The media#dom-cssimportrule-mediaReferenced in:5.4.4. The CSSImportRule Interface attribute must return the value of the media attribute of the associated CSS style sheet.

The styleSheet#dom-cssimportrule-stylesheetReferenced in:5.4.4. The CSSImportRule Interface attribute must return the associated CSS style sheet.

Note: If loading of the style sheet fails its CSS rules list is simply empty, i.e., an @import at-rule always has an associated CSS style sheet.

5.4.5. The CSSGroupingRule Interface

The CSSGroupingRule interface represents an at-rule that contains other rules nested inside itself.

interface CSSGroupingRule#cssgroupingruleReferenced in:5.4.5. The CSSGroupingRule Interface5.4.6. The CSSMediaRule Interface5.4.7. The CSSPageRule Interface : CSSRule {
  [SameObject] readonly attribute CSSRuleList cssRules;
  unsigned long insertRule(DOMString rule, unsigned long index);
  void deleteRule(unsigned long index);
};

The cssRules#dom-cssgroupingrule-cssrulesReferenced in:5.4.5. The CSSGroupingRule Interface attribute must return a CSSRuleList object for the child CSS rules.

The insertRule(rule, index)#dom-cssgroupingrule-insertruleReferenced in:5.4.5. The CSSGroupingRule Interface method must return the result of invoking insert a CSS rule rule into the child CSS rules at index.

The deleteRule(index)#dom-cssgroupingrule-deleteruleReferenced in:5.4.5. The CSSGroupingRule Interface method must remove a CSS rule from the child CSS rules at index.

5.4.6. The CSSMediaRule Interface

The CSSMediaRule interface represents an @media at-rule.

interface CSSMediaRule#cssmediaruleReferenced in:5.4. CSS Rules5.4.2. The CSSRule Interface5.4.6. The CSSMediaRule Interface : CSSGroupingRule {
  [SameObject, PutForwards=mediaText] readonly attribute MediaList media;
};

The media attribute must return a MediaList object for the list of media queries specified with the @media at-rule.

5.4.7. The CSSPageRule Interface

The CSSPageRule interface represents an @page at-rule.

Need to define the rules for parse a list of CSS page selectors#parse-a-list-of-css-page-selectorsReferenced in:5.4.7. The CSSPageRule Interface and serialize a list of CSS page selectors#serialize-a-list-of-css-page-selectorsReferenced in:5.4.7. The CSSPageRule Interface.

interface CSSPageRule#csspageruleReferenced in:5.4. CSS Rules5.4.2. The CSSRule Interface5.4.7. The CSSPageRule Interface : CSSGroupingRule {
           attribute DOMString selectorText#dom-csspagerule-selectortextReferenced in:5.4.7. The CSSPageRule Interface;
  [SameObject, PutForwards=cssText] readonly attribute CSSStyleDeclaration style;
};

The selectorText attribute, on getting, must return the result of serializing the associated list of CSS page selectors. On setting the selectorText attribute these steps must be run:

1. Run the parse a list of CSS page selectors algorithm on the given value.
2. If the algorithm returns a non-null value replace the associated list of CSS page selectors with the returned value.
3. Otherwise, if the algorithm returns a null value, do nothing.

The style attribute must return a CSSStyleDeclaration object for the @page at-rule, with the following properties:

readonly flag

Unset.

declarations

The declared declarations in the rule, in specified order.

parent CSS rule

The context object.

owner node

Null.

5.4.8. The CSSMarginRule Interface

The CSSMarginRule interface represents a margin at-rule (e.g. @top-left) in an @page at-rule. [CSS3PAGE]

interface CSSMarginRule#cssmarginruleReferenced in:5.4.2. The CSSRule Interface5.4.8. The CSSMarginRule Interface : CSSRule {
  readonly attribute DOMString name;
  [SameObject, PutForwards=cssText] readonly attribute CSSStyleDeclaration style;
};

The name#dom-cssmarginrule-nameReferenced in:5.4.8. The CSSMarginRule Interface attribute must return the name of the margin at-rule. The @ character is not included in the name. [CSS3SYN]

The style#dom-cssmarginrule-styleReferenced in:5.4.8. The CSSMarginRule Interface attribute must return a CSSStyleDeclaration object for the margin at-rule, with the following properties:

readonly flag

Unset.

declarations

The declared declarations in the rule, in specified order.

parent CSS rule

The context object.

owner node

Null.

5.4.9. The CSSNamespaceRule Interface

The CSSNamespaceRule interface represents an @namespace at-rule.

interface CSSNamespaceRule#cssnamespaceruleReferenced in:5.4. CSS Rules5.4.2. The CSSRule Interface5.4.9. The CSSNamespaceRule Interface10.1. Changes From 5 December 2013 : CSSRule {
  readonly attribute DOMString namespaceURI;
  readonly attribute DOMString prefix;
};

The namespaceURI#dom-cssnamespacerule-namespaceuriReferenced in:5.4. CSS Rules5.4.9. The CSSNamespaceRule Interface attribute must return the namespace of the @namespace at-rule.

The prefix#dom-cssnamespacerule-prefixReferenced in:5.4. CSS Rules5.4.9. The CSSNamespaceRule Interface attribute must return the prefix of the @namespace at-rule or the empty string if there is no prefix.

5.5. CSS Declarations

A CSS declaration#css-declarationReferenced in:5.5. CSS Declarations5.6. CSS Declaration Blocks (2) (3) (4) (5) (6) (7)5.6.1. The CSSStyleDeclaration Interface (2) (3) (4) (5) (6) (7) (8) (9) (10) (11) (12) (13) (14) (15) (16) (17) (18) (19) (20)5.7.2. Serializing CSS Values (2) (3) (4)6.1. The ElementCSSInlineStyle Interface is an abstract concept that is not exposed as an object in the DOM. A CSS declaration has the following associated properties:

property name#css-declaration-property-nameReferenced in:5.5. CSS Declarations5.6. CSS Declaration Blocks (2) (3)5.6.1. The CSSStyleDeclaration Interface (2) (3) (4) (5) (6) (7) (8) (9) (10)5.7.2. Serializing CSS Values (2)

The property name of the declaration.

value#css-declaration-valueReferenced in:5.6.1. The CSSStyleDeclaration Interface (2)5.7.2. Serializing CSS Values (2)

The value of the declaration represented as a list of component values.

important flag#css-declaration-important-flagReferenced in:5.6. CSS Declaration Blocks (2) (3)5.6.1. The CSSStyleDeclaration Interface (2) (3) (4) (5)

Either set or unset. Can be changed.

case-sensitive flag

Set if the property name is defined to be case-sensitive according to its specification, otherwise unset.

5.6. CSS Declaration Blocks

A CSS declaration block#css-declaration-blockReferenced in:5.6. CSS Declaration Blocks (2) (3) (4)5.6.1. The CSSStyleDeclaration Interface6.1. The ElementCSSInlineStyle Interface6.2. Extensions to the Window Interface (2) is an ordered collection of CSS properties with their associated values, also named CSS declarations. In the DOM a CSS declaration block is a CSSStyleDeclaration object. A CSS declaration block has the following associated properties:

readonly flag#cssstyledeclaration-readonly-flagReferenced in:5.4.3. The CSSStyleRule Interface5.4.7. The CSSPageRule Interface5.4.8. The CSSMarginRule Interface5.6.1. The CSSStyleDeclaration Interface (2) (3) (4) (5)6.1. The ElementCSSInlineStyle Interface6.2. Extensions to the Window Interface

Unset if the object can be manipulated. Set if it can not be manipulated. Unless otherwise stated it is unset.

declarations#cssstyledeclaration-declarationsReferenced in:5.4.3. The CSSStyleRule Interface5.4.7. The CSSPageRule Interface5.4.8. The CSSMarginRule Interface5.6. CSS Declaration Blocks (2)5.6.1. The CSSStyleDeclaration Interface (2) (3) (4) (5) (6) (7) (8) (9) (10) (11) (12) (13) (14) (15)6.1. The ElementCSSInlineStyle Interface (2) (3) (4)6.2. Extensions to the Window Interface

The CSS declarations associated with the object.

parent CSS rule#cssstyledeclaration-parent-css-ruleReferenced in:5.4.3. The CSSStyleRule Interface5.4.7. The CSSPageRule Interface5.4.8. The CSSMarginRule Interface5.6.1. The CSSStyleDeclaration Interface6.1. The ElementCSSInlineStyle Interface6.2. Extensions to the Window Interface

The CSS rule that the CSS declaration block is associated with, if any, or null otherwise.

owner node#cssstyledeclaration-owner-nodeReferenced in:5.4.3. The CSSStyleRule Interface5.4.7. The CSSPageRule Interface5.4.8. The CSSMarginRule Interface6.1. The ElementCSSInlineStyle Interface6.2. Extensions to the Window Interface

The Element that the CSS declaration block is associated with, if any, or null otherwise.

To parse a CSS declaration block#parse-a-css-declaration-blockReferenced in:5.6.1. The CSSStyleDeclaration Interface6.1. The ElementCSSInlineStyle Interface10.2. Changes From 12 July 2011 To 5 December 2013 from a string string, follow these steps:

1. Let declarations be the return value of invoking parse a list of declarations with string.
2. Let parsed declarations be a new empty list.
3. For each item declaration in declarations, follow these substeps:
   1. Let parsed declaration be the result of parsing declaration according to the appropriate CSS specifications, dropping parts that are said to be ignored. If the whole declaration is dropped, let parsed declaration be null.
   2. If parsed declaration is not null, append it to parsed declarations.
4. Return parsed declarations.

To serialize a CSS declaration#serialize-a-css-declarationReferenced in:5.6. CSS Declaration Blocks (2) with property name property, value value and optionally an important flag set, follow these steps:

1. Let s be the empty string.
2. Append property to s.
3. Append ": " (U+003A U+0020) to s.
4. Append value to s.
5. If the important flag is set, append " !important" (U+0020 U+0021 U+0069 U+006D U+0070 U+006F U+0072 U+0074 U+0061 U+006E U+0074) to s.
6. Append ";" (U+003B) to s.
7. Return s.

To serialize a CSS declaration block#serialize-a-css-declaration-blockReferenced in:5.4. CSS Rules5.6.1. The CSSStyleDeclaration Interface6.1. The ElementCSSInlineStyle Interface10.2. Changes From 12 July 2011 To 5 December 2013 declaration block means to run the steps below:

1. Let list be an empty array.
2. Let already serialized be an empty array.
3. Declaration loop: For each CSS declaration declaration in declaration block’s declarations, follow these substeps:
   1. Let property be declaration’s property name.
   2. If property is in already serialized, continue with the steps labeled declaration loop.
   3. If property maps to one or more shorthand properties, let shorthands be an array of those shorthand properties, in preferred order, and follow these substeps:
      1. Let longhands be an array consisting of all CSS declarations in declaration block’s declarations that that are not in already serialized and have a property name that maps to one of the shorthand properties in shorthands.
      2. Shorthand loop: For each shorthand in shorthands, follow these substeps:
         1. If all properties that map to shorthand are not present in longhands, continue with the steps labeled shorthand loop.
         2. Let current longhands be an empty array.
         3. Append all CSS declarations in longhands have a property name that maps to shorthand to current longhands.
         4. If there is one or more CSS declarations in current longhands have their important flag set and one or more with it unset, continue with the steps labeled shorthand loop.
         5. Let value be the result of invoking serialize a CSS value of current longhands.
         6. If value is the empty string, continue with the steps labeled shorthand loop.
         7. Let serialized declaration be the result of invoking serialize a CSS declaration with property name shorthand, value value, and the important flag set if the CSS declarations in current longhands have their important flag set.
         8. Append serialized declaration to list.
         9. Append the property names of all items of current longhands to already serialized.
         10. Remove the items present in current longhands from longhands.
   4. If property is in already serialized, continue with the steps labeled declaration loop.
   5. Let value be the result of invoking serialize a CSS value of declaration.
   6. Let serialized declaration be the result of invoking serialize a CSS declaration with property name property, value value, and the important flag set if declaration has its important flag set.
   7. Append serialized declaration to list.
   8. Append property to already serialized.
4. Return list joined with " " (U+0020).

Note: The serialization of an empty CSS declaration block is the empty string.

Note: The serialization of a non-empty CSS declaration block does not include any surrounding whitespace, i.e., no whitespace appears before the first property name and no whitespace appears after the final semicolon delimiter that follows the last property value.

The preferred order#concept-shorthands-preferred-orderReferenced in:5.6. CSS Declaration Blocks5.7.2. Serializing CSS Values of a list of shorthand properties shorthands is as follows:

1. Order shorthands lexicographically.
2. Move all items in shorthands that begin with "-" (U+002D) last in the list, retaining their relative order.
3. Move all items in shorthands that begin with "-" (U+002D) but do not begin with "-webkit-" last in the list, retaining their relative order.
4. Order shorthands by the number of longhand properties that map to it, with the greatest number first.

5.6.1. The CSSStyleDeclaration Interface

The CSSStyleDeclaration interface represents a CSS declaration block, including its underlying state, where this underlying state depends upon the source of the CSSStyleDeclaration instance.

interface CSSStyleDeclaration#cssstyledeclarationReferenced in:5.4.3. The CSSStyleRule Interface5.4.7. The CSSPageRule Interface5.4.8. The CSSMarginRule Interface5.6.1. The CSSStyleDeclaration Interface (2) (3) (4)6.1. The ElementCSSInlineStyle Interface6.2. Extensions to the Window Interface10.1. Changes From 5 December 2013 (2) {
  attribute DOMString cssText;
  readonly attribute unsigned long length;
  getter DOMString item(unsigned long index);
  DOMString getPropertyValue(DOMString property);
  DOMString getPropertyPriority(DOMString property);
  void setProperty(DOMString property, [TreatNullAs=EmptyString] DOMString value, [TreatNullAs=EmptyString] optional DOMString priority = "");
  void setPropertyValue(DOMString property, [TreatNullAs=EmptyString] DOMString value);
  void setPropertyPriority(DOMString property, [TreatNullAs=EmptyString] DOMString priority);
  DOMString removeProperty(DOMString property);
  readonly attribute CSSRule? parentRule;
  [TreatNullAs=EmptyString] attribute DOMString cssFloat;
};

The object’s supported property indices are the numbers in the range zero to one less than the number of CSS declarations in the declarations. If there are no such CSS declarations, then there are no supported property indices.

The cssText#dom-cssstyledeclaration-csstextReferenced in:5.4.3. The CSSStyleRule Interface5.4.7. The CSSPageRule Interface5.4.8. The CSSMarginRule Interface5.6.1. The CSSStyleDeclaration Interface (2)6.1. The ElementCSSInlineStyle Interface attribute must return the result of serializing the declarations. Setting the cssText attribute must run these steps:

1. If the readonly flag is set, throw a NoModificationAllowedError exception and terminate these steps.
2. Empty the declarations.
3. Parse the given value and, if the return value is not the empty list, insert the items in the list into the declarations, in specified order.

The length#dom-cssstyledeclaration-lengthReferenced in:5.6.1. The CSSStyleDeclaration Interface attribute must return the number of CSS declarations in the declarations.

The item(index)#dom-cssstyledeclaration-itemReferenced in:5.6.1. The CSSStyleDeclaration Interface method must return the property name of the CSS declaration at position index.

The getPropertyValue(property)#dom-cssstyledeclaration-getpropertyvalueReferenced in:5.6.1. The CSSStyleDeclaration Interface (2) (3) (4) (5) (6)10.2. Changes From 12 July 2011 To 5 December 2013 method must run these steps:

1. Let property be property converted to ASCII lowercase.
2. If property is a shorthand property, then follow these substeps:
   1. Let list be a new empty array.
   2. For each longhand property longhand that property maps to, in canonical order, follow these substeps:
      1. If longhand is a case-sensitive match for a property name of a CSS declaration in the declarations, let declaration be that CSS declaration, or null otherwise.
      2. If declaration is null, return the empty string and terminate these steps.
      3. Append the declaration to list.
   3. Return the serialization of list and terminate these steps.
3. If property is a case-sensitive match for a property name of a CSS declaration in the declarations, return the result of invoking serialize a CSS value of that declaration and terminate these steps.
4. Return the empty string.

The getPropertyPriority(property)#dom-cssstyledeclaration-getpropertypriorityReferenced in:5.6.1. The CSSStyleDeclaration Interface (2) method must run these steps:

1. Let property be property converted to ASCII lowercase.
2. If property is a shorthand property, follow these substeps:
   1. Let list be a new array.
   2. For each longhand property longhand that property maps to, append the result of invoking getPropertyPriority() with longhand as argument to list.
   3. If all items in list are the string "important", return the string "important" and terminate these steps.
3. Otherwise, follow these substeps:
   1. If property is a case-sensitive match for a property name of a CSS declaration in the declarations that has the important flag set, return the string "important".
4. Return the empty string.

The setProperty(property, value, priority)#dom-cssstyledeclaration-setpropertyReferenced in:5.6.1. The CSSStyleDeclaration Interface (2) (3) (4) (5)10.1. Changes From 5 December 201310.2. Changes From 12 July 2011 To 5 December 2013 method must run these steps:

1. If the readonly flag is set, throw a NoModificationAllowedError exception and terminate these steps.
2. Let property be property converted to ASCII lowercase.
3. If property is not a case-sensitive match for a supported CSS property, terminate this algorithm.
4. If value is the empty string, invoke removeProperty() with property as argument and terminate this algorithm.
5. If priority is not the empty string and is not an ASCII case-insensitive match for the string "important", terminate this algorithm.
6. Let component value list be the result of parsing value for property property.

   Note: value can not include "!important".

7. If component value list is null terminate these steps.
8. If property is a shorthand property, then for each longhand property longhand that property maps to, in canonical order, set the CSS declaration longhand with the appropriate value(s) from component value list, with the important flag set if priority is not the empty string, and unset otherwise, and with the list of declarations being the declarations.
9. Otherwise, set the CSS declaration property with value component value list, with the important flag set if priority is not the empty string, and unset otherwise, and with the list of declarations being the declarations.

To set a CSS declaration#set-a-css-declarationReferenced in:5.6.1. The CSSStyleDeclaration Interface (2) property with a value component value list and optionally with an important flag set, in a list of declarations declarations, follow these steps:

1. If property is a case-sensitive match for a property name of a CSS declaration in declarations, let declaration be that CSS declaration.
2. Otherwise, append a new CSS declaration with the property name property to declarations and let declaration be that CSS declaration.
3. Set declaration’s value to component value list.
4. If the important flag is set, set declaration’s important flag. Otherwise, unset declaration’s important flag.

The setPropertyValue(property, value)#dom-cssstyledeclaration-setpropertyvalueReferenced in:5.6.1. The CSSStyleDeclaration Interface10.2. Changes From 12 July 2011 To 5 December 2013 method must run these steps:

1. If the readonly flag is set, throw a NoModificationAllowedError exception and terminate these steps.
2. Let property be property converted to ASCII lowercase.
3. If property is not a case-sensitive match for a supported CSS property, terminate this algorithm.
4. If value is the empty string, invoke removeProperty() with property as argument and terminate this algorithm.
5. Let component value list be the result of parsing value for property property.

   Note: value can not include "!important".

6. If component value list is null terminate these steps.
7. If property is a shorthand property, then for each longhand property longhand that property maps to, in canonical order, set the CSS declaration value longhand to the appropriate value(s) from component value list, and with the list of declarations being the declarations.
8. Otherwise, set the CSS declaration value property to the value component value list, and with the list of declarations being the declarations.

To set a CSS declaration value#set-a-css-declaration-valueReferenced in:5.6.1. The CSSStyleDeclaration Interface (2) to a value component value list in a list of declarations declarations, follow these steps:

1. If property is a case-sensitive match for a property name of a CSS declaration in declarations, let declaration be that CSS declaration.
2. Otherwise, append a new CSS declaration with the property name property to declarations and let declaration be that CSS declaration.
3. Set declaration’s value to component value list.

The setPropertyPriority(property, priority)#dom-cssstyledeclaration-setpropertypriorityReferenced in:5.6.1. The CSSStyleDeclaration Interface10.2. Changes From 12 July 2011 To 5 December 2013 method must run these steps:

1. If the readonly flag is set, throw a NoModificationAllowedError exception and terminate these steps.
2. Let property be property converted to ASCII lowercase.
3. If property is not a case-sensitive match for a supported CSS property, terminate this algorithm.
4. If priority is not the empty string and is not an ASCII case-insensitive match for the string "important", terminate this algorithm.
5. If property is a shorthand property, then for each longhand property longhand that property maps to, in canonical order, set the CSS declaration priority longhand with the important flag set if priority is not the empty string, and unset otherwise, and with the list of declarations being the declarations.
6. Otherwise, set the CSS declaration priority property with the important flag set if priority is not the empty string, and unset otherwise, and with the list of declarations being the declarations.

To set a CSS declaration priority#set-a-css-declaration-priorityReferenced in:5.6.1. The CSSStyleDeclaration Interface (2) property optionally with an important flag set, in a list of declarations declarations, follow these steps:

1. If property is a case-sensitive match for a property name of a CSS declaration in declarations, let declaration be that CSS declaration.
2. Otherwise, terminate these steps.
3. If the important flag is set, set declaration’s important flag. Otherwise, unset declaration’s important flag.

The removeProperty(property)#dom-cssstyledeclaration-removepropertyReferenced in:5.6.1. The CSSStyleDeclaration Interface (2) (3) (4) method must run these steps:

1. If the readonly flag is set, throw a NoModificationAllowedError exception and terminate these steps.
2. Let property be property converted to ASCII lowercase.
3. Let value be the return value of invoking getPropertyValue() with property as argument.
4. If property is a shorthand property, for each longhand property longhand that property maps to, invoke removeProperty() with longhand as argument.
5. Otherwise, if property is a case-sensitive match for a property name of a CSS declaration in the declarations, remove that CSS declaration.
6. Return value.

The parentRule#dom-cssstyledeclaration-parentruleReferenced in:5.6.1. The CSSStyleDeclaration Interface attribute must return the parent CSS rule.

The cssFloat#dom-cssstyledeclaration-cssfloatReferenced in:5.6.1. The CSSStyleDeclaration Interface attribute, on getting, must return the result of invoking getPropertyValue() with float as argument. On setting, the attribute must invoke setProperty() with float as first argument, as second argument the given value, and no third argument. Any exceptions thrown must be re-thrown.

For each CSS property property that is a supported CSS property, the following partial interface applies where camel-cased attribute is obtained by running the CSS property to IDL attribute algorithm for property.

partial interface CSSStyleDeclaration {
  [TreatNullAs=EmptyString] attribute DOMString _camel_cased_attribute;
};

The camel-cased attribute#dom-cssstyledeclaration-camel-cased-attributeReferenced in:5.6.1. The CSSStyleDeclaration Interface attribute, on getting, must return the result of invoking getPropertyValue() with the argument being the result of running the IDL attribute to CSS property algorithm for camel-cased attribute.

Setting the camel-cased attribute attribute must invoke setProperty() with the first argument being the result of running the IDL attribute to CSS property algorithm for camel-cased attribute, as second argument the given value, and no third argument. Any exceptions thrown must be re-thrown.

For each CSS property property that is a supported CSS property and that begins with the string -webkit-, the following partial interface applies where webkit-cased attribute is obtained by running the CSS property to IDL attribute algorithm for property, with the lowercase first flag set.

partial interface CSSStyleDeclaration {
  [TreatNullAs=EmptyString] attribute DOMString _webkit_cased_attribute;
};

The webkit-cased attribute#dom-cssstyledeclaration-webkit-cased-attributeReferenced in:5.6.1. The CSSStyleDeclaration Interface attribute, on getting, must return the result of invoking getPropertyValue() with the argument being the result of running the IDL attribute to CSS property algorithm for webkit-cased attribute, with the dash prefix flag set.

Setting the webkit-cased attribute attribute must invoke setProperty() with the first argument being the result of running the IDL attribute to CSS property algorithm for webkit-cased attribute, with the dash prefix flag set, as second argument the given value, and no third argument. Any exceptions thrown must be re-thrown.

For each CSS property property that is a supported CSS property, except for properties that have no "-" (U+002D) in the property name, the following partial interface applies where dashed attribute is property.

partial interface CSSStyleDeclaration {
  [TreatNullAs=EmptyString] attribute DOMString _dashed_attribute;
};

The dashed attribute#dom-cssstyledeclaration-dashed-attributeReferenced in:5.6.1. The CSSStyleDeclaration Interface attribute, on getting, must return the result of invoking getPropertyValue() with the argument being dashed attribute.

Setting the dashed attribute attribute must invoke setProperty() with the first argument being dashed attribute, as second argument the given value, and no third argument. Any exceptions thrown must be re-thrown.

element.style['font-size'];

The CSS property to IDL attribute#css-property-to-idl-attributeReferenced in:5.6.1. The CSSStyleDeclaration Interface (2) algorithm for property, optionally with a lowercase first flag set, is as follows:

1. Let output be the empty string.
2. Let uppercase next be unset.
3. If the lowercase first flag is set, remove the first character from property.
4. For each character c in property:
   1. If c is "-" (U+002D), let uppercase next be set.
   2. Otherwise, if uppercase next is set, let uppercase next be unset and append c converted to ASCII uppercase to output.
   3. Otherwise, append c to output.
5. Return output.

The IDL attribute to CSS property#idl-attribute-to-css-propertyReferenced in:5.6.1. The CSSStyleDeclaration Interface (2) (3) (4) algorithm for attribute, optionally with a dash prefix flag set, is as follows:

1. Let output be the empty string.
2. If the dash first flag is set, append "-" (U+002D) to output.
3. For each character c in attribute:
   1. If c is in the range U+0041 to U+005A (ASCII uppercase), append "-" (U+002D) followed by c converted to ASCII lowercase to output.
   2. Otherwise, append c to output.
4. Return output.

5.7. CSS Values

5.7.1. Parsing CSS Values

To parse a CSS value#parse-a-css-valueReferenced in:5.6.1. The CSSStyleDeclaration Interface (2)5.7.1. Parsing CSS Values value for a given property means to follow these steps:

1. Let list be the value returned by invoking parse a list of component values from value.
2. Match list against the grammar for the property property in the CSS specification.
3. If the above step failed, return null.
4. Return list.

Note: "!important" declarations are not part of the property value space and will therefore cause parse a CSS value to return null.

5.7.2. Serializing CSS Values

To serialize a CSS value#serialize-a-css-valueReferenced in:5.6. CSS Declaration Blocks (2)5.6.1. The CSSStyleDeclaration Interface (2)5.7.2. Serializing CSS Values of a CSS declaration declaration or a list of longhand CSS declarations list, follow these rules:

1. If this algorithm is invoked with a list list, follow these substeps:
   1. Let shorthand be the shorthand property that exactly maps to all the longhand properties in list. If there are multiple such shorthand properties, use the first in preferred order.
   2. If shorthand cannot represent the values of list in its grammar, return the empty string and terminate these steps.
   3. Let trimmed list be a new empty array.
   4. For each CSS declaration declaration in list, if declaration’s value is not the initial value, or if declaration is a required component of the shorthand property, append declaration to trimmed list.
   5. If trimmed list is empty, append the value of the first item in list to trimmed list.
   6. Let values be a new empty array.
   7. For each CSS declaration declaration in trimmed list, invoke serialize a CSS value of declaration, and append the result to values.
   8. Return the result of joining values as appropriate according to the grammar of shorthand and terminate these steps.
2. Let values be a new empty array.
3. Append the result of invoking serialize a CSS component value of declaration’s value to values.
4. If the grammar of the property name of declaration is defined to be whitespace-separated, return the result of invoking serialize a whitespace-separated list of values and terminate these steps.
5. If the grammar of the property name of declaration is defined to be comma-separated, return the result of invoking serialize a comma-separated list of values.

To serialize a CSS component value#serialize-a-css-component-valueReferenced in:5.7.2. Serializing CSS Values (2) (3) depends on the component, as follows:

keyword

The keyword converted to ASCII lowercase.

<angle>

The <number> component serialized as per <number> followed by the unit in canonical form as defined in its respective specification.

<color>

If <color> is a component of a resolved or computed value, then return the color using the rgb() or rgba() functional notation as follows:

1. If the alpha component of the color is equal to one, then return the serialization of the rgb() functional equivalent of the opaque color.
2. If the alpha component of the color is not equal to one, then return the serialization of the rgba() functional equivalent of the non-opaque color.

The serialization of the rgb() functional equivalent is the concatenation of the following:

1. The string "rgb(".
2. The shortest base-ten integer serialization of the color’s red component.
3. The string ", ".
4. The shortest base-ten serialization of the color’s green component.
5. The string ", ".
6. The shortest base-ten serialization of the color’s blue component.
7. The string ")".

The serialization of the rgba() functional equivalent is the concatenation of the following:

1. The string "rgba(".
2. The shortest base-ten serialization of the color’s red component.
3. The string ", ".
4. The shortest base-ten serialization of the color’s green component.
5. The string ", ".
6. The shortest base-ten serialization of the color’s blue component.
7. The string ", ".
8. The serialization of the color’s alpha component as an <alphavalue>.
9. The string ")".

In the above rules, the string ", " denotes a COMMA (U+002C) followed by a single SPACE (U+0020).

If <color> is a component of a specified value, then return the color as follows:

1. If the color was explicitly specified by the author, then return the original, author specified color value.
2. Otherwise, return the value that would be returned if the color were a component of a computed value.

Should author specified values be normalized for case? Or should original case be preserved?

<alphavalue>

If the value is internally represented as an integer between 0 and 255 inclusive (i.e. 8-bit unsigned integer), follow these steps:

1. Let alpha be the given integer.
2. If there exists an integer between 0 and 100 inclusive that, when multiplied with 2.55 and rounded to the closest integer (rounding up if two values are equally close), equals alpha, let rounded be that integer divided by 100.
3. Otherwise, let rounded be alpha divided by 0.255 and rounded to the closest integer (rounding up if two values are equally close), divided by 1000.
4. Return the result of serializing rounded as a <number>.

Otherwise, return the result of serializing the given value as a <number>.

<counter>

The return value of the following algorithm:

1. Let s be the empty string.
2. If <counter> has three CSS component values append the string "counters(" to s.
3. If <counter> has two CSS component values append the string "counter(" to s.
4. Let list be a list of CSS component values belonging to <counter>, omitting the last CSS component value if it is "decimal".
5. Let each item in list be the result of invoking serialize a CSS component value on that item.
6. Append the result of invoking serialize a comma-separated list on list to s.
7. Append ")" (U+0029) to s.
8. Return s.

<frequency>

The frequency in hertz serialized as per <number> followed by the literal string "hz".

<identifier>

The identifier escaped.

<integer>

A base-ten integer using digits 0-9 (U+0030 to U+0039) in the shortest form possible, preceded by "-" (U+002D) if it is negative.

<length>

A length of zero is represented by the literal string "0px".

Absolute lengths: the number of millimeters serialized as per <number> followed by the literal string "mm".

Rumor has it absolute lengths will become relative lengths. Centimeters would be compatible with <resolution>...

Relative lengths: the <number> component serialized as per <number> followed by the unit in its canonical form as defined in its respective specification.

<number>

A base-ten number using digits 0-9 (U+0030 to U+0039) in the shortest form possible, using "." to separate decimals (if any), rounding the value if necessary to not produce more than 6 decimals, preceded by "-" (U+002D) if it is negative.

Note: scientific notation is not used.

<percentage>

The <number> component serialized as per <number> followed by the literal string "%" (U+0025).

<resolution>

The resolution in dots per centimeter serialized as per <number> followed by the literal string "dpcm".

<shape>

The return value of the following algorithm:

1. Let s be the string "rect(".
2. Let list be a list of the CSS component values belonging to <shape>.
3. Let each item in list be the result of invoking serialize a CSS component value of that item.
4. Append the result of invoking serialize a comma-separated list on list to s.
5. Append ")" (U+0029) to s.
6. Return s.

<string>

<family-name>

<specific-voice>

The string string escaped.

<time>

The time in seconds serialized as per <number> followed by the literal string "s".

<uri>

The absolute URL URL escaped.

<absolute-size>, <border-width>, <border-style>, <bottom>, <generic-family>, <generic-voice>, <left>, <margin-width>, <padding-width>, <relative-size>, <right>, and <top>, are considered macros by this specification. They all represent instances of components outlined above.

One idea is that we can remove this section somewhere in the CSS3/CSS4 timeline by moving the above definitions to the drafts that define the CSS components.

5.7.2.1. Examples

Here are some examples of before and after results on specified values. The before column could be what the author wrote in a style sheet, while the after column shows what querying the DOM would return.

6. DOM Access to CSS Declaration Blocks

6.1. The ElementCSSInlineStyle Interface

The ElementCSSInlineStyle interface provides access to inline style properties of an element.

[NoInterfaceObject]
interface ElementCSSInlineStyle#elementcssinlinestyleReferenced in:6.1. The ElementCSSInlineStyle Interface (2) (3) {
  [SameObject, PutForwards=cssText] readonly attribute CSSStyleDeclaration style;
};

The style#dom-elementcssinlinestyle-styleReferenced in:6.1. The ElementCSSInlineStyle Interface attribute must return a live CSS declaration block with the following properties:

readonly flag

Unset.

declarations

The result of parsing the style content attribute, in specified order. If the style content attribute is absent, the object represents an empty list of CSS declarations. Mutating the declarations must set the style content attribute on the context object to the serialization of the declarations. If the style content attribute is set, changed or removed, the declarations must be updated as appropriate.

parent CSS rule

Null.

owner node

The context object.

If the user agent supports HTML, the following IDL applies: [HTML]

HTMLElement implements ElementCSSInlineStyle;

If the user agent supports SVG, the following IDL applies: [SVG]

SVGElement implements ElementCSSInlineStyle;

6.2. Extensions to the Window Interface

partial interface Window {
  [NewObject] CSSStyleDeclaration getComputedStyle(Element elt, optional DOMString? pseudoElt);
};

The getComputedStyle(elt, pseudoElt)#dom-window-getcomputedstyleReferenced in:6.2. Extensions to the Window Interface (2) (3)8. Resolved Values (2) method must run these steps:

1. Let doc be the Document associated with the Window object on which the method was invoked.
2. Let obj be elt.
3. If pseudoElt is as an ASCII case-insensitive match for either ':before' or '::before' let obj be the ::before pseudo-element of elt.
4. If pseudoElt is as an ASCII case-insensitive match for either ':after' or '::after' let obj be the ::after pseudo-element of elt.
5. Return a live CSS declaration block with the following properties:

   readonly flag

   Set.

   declarations

   All longhand properties that are supported CSS properties, in lexicographical order, with the value being the resolved value computed for obj using the style rules associated with doc.

   Note: This means that even if obj is in a different document (e.g. one fetched via XMLHttpRequest) it will still use the style rules associated with the document that is associated with the global object on which getComputedStyle() was invoked to compute the CSS declaration block.

   parent CSS rule

   Null.

   owner node

   obj.

The getComputedStyle() method exposes information from CSS style sheets with the origin-clean flag unset.

7. Utility APIs

7.1. The CSS.escape() Method

The CSS interface holds useful CSS-related functions that do not belong elsewhere.

interface CSS {
  static DOMString escape(DOMString ident);
};

The escape(ident)#dom-css-escapeReferenced in:7.1. The CSS.escape() Method (2) (3)10.2. Changes From 12 July 2011 To 5 December 2013 method must return the result of invoking serialize an identifier of ident.

var element = document.querySelector('#' + CSS.escape(id) + ' > img');

var element = document.querySelector('a[href="#' + CSS.escape(fragment) + '"]');

8. Resolved Values

getComputedStyle() was historically defined to return the "computed value" of an element or pseudo-element. However, the concept of "computed value" changed between revisions of CSS while the implementation of getComputedStyle() had to remain the same for compatibility with deployed scripts. To address this issue this specification introduces the concept of a resolved value#resolved-valueReferenced in:6.2. Extensions to the Window Interface8. Resolved Values (2) (3) (4) (5) (6) (7) (8) (9).

The resolved value for a given property can be determined as follows:

line-height

The resolved value is the used value.

height

margin

margin-bottom

margin-left

margin-right

margin-top

padding

padding-bottom

padding-left

padding-right

padding-top

width

If the property applies to the element or pseudo-element and the resolved value of the display property is not none, the resolved value is the used value. Otherwise the resolved value is the computed value.

bottom

left

right

top

If the property applies to a positioned element and the resolved value of the display property is not none, the resolved value is the used value. Otherwise the resolved value is the computed value.

Any other property

The resolved value is the computed value.

9. IANA Considerations

9.1. Default-Style

This section describes a header field for registration in the Permanent Message Header Field Registry.

Header field name

Default-Style#http-default-styleReferenced in:5.2.1. The HTTP Default-Style Header (2)

Applicable protocol

http

Status

standard

Author/Change controller

W3C

Specification document(s)

This document is the relevant specification.

Related information

None.

10. Change History

This section documents some of the changes between publications of this specification. This section is not exhaustive. Bug fixes and editorial changes are generally not listed.

10.1. Changes From 5 December 2013

• API for alternative stylesheets is removed: selectedStyleSheetSet, lastStyleSheetSet, preferredStyleSheetSet, styleSheetSets, enableStyleSheetsForSet() on Document.

• The pseudo() method on Element and the PseudoElement interface is removed.

• The cascadedStyle, defaultStyle, rawComputedStyle and usedStyle IDL attributes on Element are removed.

• The cssText IDL attribute’s setter on CSSRule is changed to do nothing.

• IDL attributes of the form webkitFoo (with lowercase w) on CSSStyleDeclaration are added.

• CSSNamespaceRule is changed back to readonly.

• Handling of @charset in insertRule() is removed.

• CSSCharsetRule is removed again.

• Serialization of identifiers and strings is changed.

• Serialization of selectors now supports combinators ">>" and "||" and the "i" flag in attribute selectors.

• Serialization of :lang() is changed.

• Serialization of <color> and <number> is changed.

• setProperty() on CSSStyleDeclaration is changed.

10.2. Changes From 12 July 2011 To 5 December 2013

• Cross-origin stylesheets are not allowed to be read or changed.
• CSSCharsetRule is re-introduced.
• CSSGroupingRule and CSSMarginRule are introduced.
• CSSNamespaceRule is now mutable.
• Parse and serialize a CSS declaration block is now defined.
• Shorthands are now supported in setProperty(), getPropertyValue(), et al.
• setPropertyValue() and setPropertyPriority() are introduced.
• The style and media attributes of various interfaces are annotated with the [PutForwards] WebIDL extended attribute.
• The pseudo() method on Element is introduced.
• The PseudoElement interface is introduced.
• The cascadedStyle, rawComputedStyle and usedStyle attributes on Element and PseudoElement are introduced.
• The CSS.escape() static method is introduced.

11. Acknowledgments

The editors would like to thank Alexey Feldgendler, Benjamin Poulain, Björn Höhrmann, Boris Zbasky, Brian Kardell, Christian Krebs, Daniel Glazman, David Baron, fantasai, Hallvord R. M. Steen, Ian Hickson, John Daggett, Lachlan Hunt, Mike Sherov, Morten Stenshorne, Ms2ger, Øyvind Stenhaug, Peter Sloetjes, Philip Jägenstedt, Philip Taylor, Richard Gibson, Robert O’Callahan, Simon Sapin, Sjoerd Visscher, Sylvain Galineau, Tarquin Wilton-Jones, and Zack Weinberg for contributing to this specification.

Additional thanks to Ian Hickson for writing the initial version of the alternative style sheets API and canonicalization (now serialization) rules for CSS values.