Title: CSS Object Model (CSSOM)
ED: https://drafts.csswg.org/cssom/
TR: https://www.w3.org/TR/cssom-1/
Previous Version: https://www.w3.org/TR/2021/WD-cssom-1-20210826/
Previous Version: https://www.w3.org/TR/2016/WD-cssom-1-20160317/
Previous Version: https://www.w3.org/TR/2013/WD-cssom-20131205/
Previous Version: https://www.w3.org/TR/2011/WD-cssom-20110712/
Previous Version: https://www.w3.org/TR/2000/REC-DOM-Level-2-Style-20001113/
Group: CSSWG
Status: ED
Prepare for TR: no
Work Status: Exploring
Shortname: cssom
Level: 1
Editor: Daniel Glazman, Disruptive Innovations http://disruptive-innovations.com/, daniel.glazman@disruptive-innovations.com, w3cid 13329
Editor: Emilio Cobos Álvarez 106537, Mozilla, emilio@mozilla.com
Former Editor: Simon Pieters, Opera Software AS http://www.opera.com, simonp@opera.com
Former Editor: Glenn Adams, Cox Communications, Inc. http://www.cox.com, glenn.adams@cos.com, http://www.w3.org/wiki/User:Gadams
Former Editor: Anne van Kesteren, Opera Software ASA http://www.opera.com, annevk@annevk.nl, https://annevankesteren.nl/
!Legacy issues list: Bugzilla
Abstract: CSSOM defines APIs (including generic parsing and serialization rules) for Media Queries, Selectors, and of course CSS itself.
Repository: w3c/csswg-drafts
Ignored Terms: EmptyString, group of selectors, list of css page selectors, -webkit-transform
Ignored Vars: m1, m2, camel_cased_attribute, webkit_cased_attribute, dashed_attribute
Include Can I Use Panels: true
Can I Use URL: https://drafts.csswg.org/cssom/
Can I Use URL: https://www.w3.org/TR/cssom-1/
Ignore Can I Use URL Failure: https://drafts.csswg.org/cssom/
Ignore Can I Use URL Failure: https://www.w3.org/TR/cssom-1/
urlPrefix: https://html.spec.whatwg.org/multipage/
urlPrefix: infrastructure.html
type: dfn
text: html elements
text: tree order
text: content-type metadata; url: #content-type
urlPrefix: urls-and-fetching.html
type: dfn
text: document base url
urlPrefix: rendering.html
type: dfn
text: being rendered
urlPrefix: browsers.html
type: interface; text: WindowProxy
type: dfn
text: browsing context
text: auxiliary browsing context
text: familiar with
text: same origin
urlPrefix: webappapis.html
type: dfn
text: responsible browsing context
text: incumbent settings object
text: event loop
text: event handlers
text: event handler event type
text: event handler IDL attributes
urlPrefix: infrastructure.html
type: dfn
text: split a string on commas
text: skip whitespace
text: collect a sequence of characters
text: space character
text: rules for parsing integers
urlPrefix: xhtml.html
type: dfn
text: xml parser
urlPrefix: semantics.html
type: dfn
text: a style sheet that is blocking scripts
text: contributes a script-blocking style sheet
for: Document
text: script-blocking style sheet set
urlPrefix: https://dom.spec.whatwg.org/#concept-
type: dfn
text: dispatch; url: event-dispatch
text: event
text: event listener
text: quirks mode; url: document-quirks
text: fire an event; url: event-fire
text: node document
text: document url
urlPrefix: https://www.w3.org/TR/CSS21/visuren.html
type: dfn; text: anonymous block box; url: #anonymous-block-level
urlPrefix: http://heycam.github.io/webidl/#
type: interface; urlPrefix: idl-
text: double
text: long
type: dfn; urlPrefix: dfn-
text: converted to an IDL value
text: throw
text: supported property indices
urlPrefix: https://encoding.spec.whatwg.org/#; spec: ENCODING
type: dfn; text: get an encoding; url: concept-encoding-get
urlPrefix: https://url.spec.whatwg.org/#concept-
type: dfn
text: URL
text: URL parser
text: URL serializer
urlPrefix: https://www.w3.org/TR/xml-stylesheet/#dt-
type: dfn;
text: xml-stylesheet processing instruction; url: xml-stylesheet
type: dfn; text: pseudo-attribute
urlPrefix: https://fetch.spec.whatwg.org/#concept-
type: dfn;
text: fetch
text: request
for: request
text: url; url: request-url
text: origin; url: request-origin
text: referrer; url: request-referrer
text: network error
Introduction {#introduction}
============================
This document formally specifies the core features of the CSS Object Model (CSSOM). Other documents in the CSSOM family of specifications
as well as other CSS related specifications define extensions to these core features.
The core features of the CSSOM are oriented towards providing basic capabilities to author-defined scripts to permit access to
and manipulation of style related state information and processes.
The features defined below are fundamentally based on prior specifications of the W3C DOM Working Group, primarily
[[DOM]]. The purposes of the present document are (1) to improve on that prior work by providing
more technical specificity (so as to improve testability and interoperability), (2) to deprecate or remove certain less-widely implemented
features no longer considered to be essential in this context, and (3) to newly specify certain extensions that have been
or expected to be widely implemented.
Terminology {#terminology}
==========================
This specification employs certain terminology from the following documents:
DOM,
HTML,
CSS Syntax,
Encoding,
URL,
Fetch,
Associating Style Sheets with XML documents
and
XML.
[[!DOM]]
[[!HTML]]
[[!CSS3SYN]]
[[!ENCODING]]
[[!URL]]
[[!FETCH]]
[[!XML-STYLESHEET]]
[[!XML]]
When this specification talks about object
A where A is actually an interface, it generally means an object implementing interface
A.
The terms set and unset to refer to the true and
false values of binary flags or variables, respectively. These terms are also used as verbs in which case they refer to
mutating some value to make it true or false, respectively.
The term supported styling language refers to CSS.
Note: If another styling language becomes supported in user agents, this specification is expected to be updated as necessary.
The term supported CSS property refers to a CSS property that the user agent
implements, including any vendor-prefixed properties, but excluding custom properties. A
supported CSS property must be in its lowercase form for the purpose of comparisons in this
specification.
In this specification the ''::before'' and ''::after'' pseudo-elements
are assumed to exist for all elements even if no box is generated for them.
When a method or an attribute is said to call another method or attribute, the user agent must invoke its internal API for that attribute or method so that
e.g. the author can't change the behavior by overriding attributes or methods with custom properties or functions in ECMAScript.
Unless otherwise stated, string comparisons are done in a case-sensitive manner.
Common Serializing Idioms {#common-serializing-idioms}
------------------------------------------------------
To escape a character means to create a string of
"\" (U+005C), followed by the character.
To escape a character as code point means to create a
string of "\" (U+005C), followed by the Unicode code point as
the smallest possible number of hexadecimal digits in the range 0-9 a-f
(U+0030 to U+0039 and U+0061 to U+0066) to represent the code point in
base 16, followed by a single SPACE (U+0020).
To serialize an identifier means to create a string represented
by the concatenation of, for each character of the identifier:
If the character is NULL (U+0000), then the REPLACEMENT CHARACTER (U+FFFD).
If the character is in the range [\1-\1f] (U+0001 to U+001F) or is U+007F, then the character
escaped as code point.
If the character is the first character and is in the range \[0-9]
(U+0030 to U+0039), then the character
escaped as code point.
If the character is the second character and is in the range \[0-9]
(U+0030 to U+0039) and the first character is a "-"
(U+002D), then the character
escaped as code point.
If the character is the first character and is a "-" (U+002D),
and there is no second character,
then the escaped character.
If the character is not handled by one of the above rules and is
greater than or equal to U+0080, is "-" (U+002D) or
"_" (U+005F), or is in one of the ranges \[0-9] (U+0030 to
U+0039), \[A-Z] (U+0041 to U+005A), or \[a-z] (U+0061 to U+007A), then the character
itself.
To serialize a string means to create a string represented
by '"' (U+0022), followed by the result of applying the rules
below to each character of the given string, followed by
'"' (U+0022):
If the character is NULL (U+0000), then the REPLACEMENT CHARACTER (U+FFFD).
If the character is in the range [\1-\1f] (U+0001 to U+001F) or is U+007F, the character
escaped as code point.
If the character is '"' (U+0022) or "\"
(U+005C), the escaped character.
Otherwise, the character itself.
Note: "'" (U+0027) is not escaped because strings
are always serialized with '"' (U+0022).
To serialize a URL means to create a string represented by
"url(", followed by the
serialization of the URL as a
string, followed by ")".
To serialize a LOCAL means to create a string represented by
"local(", followed by the
serialization of the LOCAL as a
string, followed by ")".
To serialize a comma-separated list concatenate all items of
the list in list order while separating them by ", ", i.e.,
COMMA (U+002C) followed by a single SPACE (U+0020).
To serialize a whitespace-separated list concatenate all
items of the list in list order while separating them by "", i.e.,
a single SPACE (U+0020).
Note: When serializing a list according to the above rules,
extraneous whitespace is not inserted prior to the first item or subsequent to
the last item. Unless otherwise specified, an empty list is serialized as the
empty string.
CSSOMString {#cssomstring-type}
===============================
Most strings in CSSOM interfaces use the CSSOMString type.
Each implementation chooses to define it as either {{USVString}} or {{DOMString}}:
typedef USVString CSSOMString;
Or, alternatively:
typedef DOMString CSSOMString;
The difference is only observable from web content
when surrogate code units are involved.
{{DOMString}} would preserve them,
whereas {{USVString}} would replace them with U+FFFD REPLACEMENT CHARACTER.
This choice effectively allows implementations to do this replacement,
but does not require it.
Using {{USVString}} enables an implementation
to use UTF-8 internally to represent strings in memory.
Since well-formed UTF-8 specifically disallows surrogate code points,
it effectively requires this replacement.
On the other hand,
implementations that internally represent strings as 16-bit code units
might prefer to avoid the cost of doing this replacement.
Media Queries {#media-queries}
==============================
[=Media queries=] are defined by [[!MEDIAQUERIES]]. This
section defines various concepts around [=media queries=], including their API
and serialization form.
Parsing Media Queries {#parsing-media-queries}
----------------------------------------------
To parse a media query list for a
given string s into a [=media query list=] is defined in
the Media Queries specification. Return the list of media
queries that the algorithm defined there gives.
Note: A media query that ends up being "ignored" will turn
into "not all".
To parse a media query for a given string
s means to follow the
parse a media query list steps and return null if more
than one media query is returned or a media query if a
single media query is returned.
Note: Again, a media query that ends up being "ignored" will
turn into "not all".
Serializing Media Queries {#serializing-media-queries}
------------------------------------------------------
To
serialize a media query list
run these steps:
If the [=media query list=] is empty, then return the empty string.
Serialize each media query in the list of media queries, in the same order as they appear in the [=media query list=], and then serialize the list.
To
serialize a media query let
s be the empty string, run the steps below:
If the [=media query=] is negated append "not", followed
by a single SPACE (U+0020), to s.
If the [=media query=] does not contain [=media features=] append
type, to s,
then return s.
If type is not "all" or if the
media query is negated append type, followed by a
single SPACE (U+0020), followed by "and", followed by a single SPACE
(U+0020), to s.
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.
Append a ")" (U+0029) to
s.
If this is not the last [=media feature=] append a single SPACE (U+0020),
followed by "and", followed by a single SPACE (U+0020), to
s.
Return s.
Here are some examples of input (first column) and output (second
column):
Input
Output
not screen and (min-WIDTH:5px) AND (max-width:40px)
not screen and (min-width: 5px) and (max-width: 40px)
all and (color) and (color)
(color) and (color)
### Serializing Media Feature Values ### {#serializing-media-feature-values}
Issue: 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
named v locate v in the first
column of the table below and use the serialization format described in
the second column:
Media Feature
Serialization
'@media/width'
...
'@media/height'
...
'device-width'
...
'device-height'
...
'orientation'
If the value is ''portrait'': "portrait".
If the value is ''landscape'': "landscape".
'aspect-ratio'
...
'device-aspect-ratio'
...
'@media/color'
...
'color-index'
...
'monochrome'
...
'resolution'
...
'scan'
If the value is ''progressive'': "progressive".
If the value is ''interlace'': "interlace".
'grid'
...
Other specifications can extend this table and vendor-prefixed media
features can have custom serialization formats as well.
Comparing Media Queries {#comparing-media-queries}
--------------------------------------------------
To
compare media queries
m1 and m2 means to
serialize them both and
return true if they are a
case-sensitive match and false if they
are not.
The {{MediaList}} Interface {#the-medialist-interface}
------------------------------------------------------
An object that implements the MediaList interface has an associated collection of media queries.
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 with a string text, run the following steps:
Create a new MediaList object.
Set its {{MediaList/mediaText}} attribute to text.
Return the newly created MediaList object.
The mediaText attribute, on getting, must return a
serialization of the collection of media queries.
Setting the {{MediaList/mediaText}} attribute must run these steps:
The item(index) method must return a
serialization of 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 attribute must return the number of media queries in the collection of media
queries.
The appendMedium(medium) method must run these steps:
Remove any media query from the collection of media queries for which
comparing the media query with m returns true.
If nothing was removed, then throw a {{NotFoundError}} exception.
Selectors {#selectors}
======================
Selectors are defined in the Selectors specification. This section
mainly defines how to serialize them.
Parsing Selectors {#parsing-selectors}
--------------------------------------
To
parse a group of selectors
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.
Serializing Selectors {#serializing-selectors}
----------------------------------------------
To
serialize a group of selectors
serialize each selector in the
group of selectors and then
serialize a
comma-separated list of these serializations.
To serialize a selector let
s be the empty string, run the steps below for each
part of the chain of the selector, and finally return
s:
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.
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
let s be the empty string, run the steps below, and
finally return s:
If the namespace prefix maps to a namespace that is
the null namespace (not in a namespace) append
"|" (U+007C) to s.
If this is a type selector append the
serialization of the element name
as an identifier to s.
If this is a universal selector append "*" (U+002A)
to s.
attribute selector
Append "[" (U+005B) to
s.
If the namespace prefix maps to a namespace that is
not the null namespace (not in a namespace) append the
serialization of the
namespace prefix as an identifier, followed by a
"|" (U+007C) to s.
Append the serialization
of the attribute name as an identifier to s.
If there is an attribute value specified, append
"=",
"~=",
"|=",
"^=",
"$=", or
"*="
as appropriate (depending on the type of attribute selector), followed
by the serialization of the
attribute value as a string, to s.
If the attribute selector has the case-sensitivity flag present,
append " i" (U+0020 U+0069) to s.
Append "]" (U+005D) to
s.
class selector
Append a "." (U+002E), followed by the
serialization of the class name
as an identifier to s.
ID selector
Append a "#" (U+0023), followed by the
serialization of the ID
as an identifier 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.
CSS {#css-object-model}
=======================
CSS Style Sheets {#css-style-sheets}
------------------------------------
A CSS style sheet 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.
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
{{MediaList/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 {{MediaList/mediaText}} attribute does not
change the corresponding attribute on the owner node.
Note: The owner node of a CSS style sheet, if non-null, is the node whose associated
CSS style sheet is the CSS style sheet in question, when the CSS style sheet is added.
title
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.
Note: HTML only specifiestitle to be an attribute of the owner node
if the node is in in a document tree.
alternate flag
Specified when created. Either set or unset. Unset by default.
Specified when created. Either set or unset. If it is set, the API allows reading and modifying of the CSS rules.
constructed flag
Specified when created. Either set or unset. Unset by default.
Signifies whether this stylesheet was created by invoking the IDL-defined constructor.
disallow modification flag
Either set or unset. Unset by default. If set, modification of the stylesheet's rules is not allowed.
constructor document
Specified when created. The {{Document}} a constructed stylesheet is associated with. Null by default.
Only non-null for stylesheets that have constructed flag set.
stylesheet base URL
The base URL to use when resolving relative URLs in the stylesheet. Null by default.
Only non-null for stylesheets that have constructed flag set.
### The {{StyleSheet}} Interface ### {#the-stylesheet-interface}
The {{StyleSheet}} interface represents an abstract, base style sheet.
The type attribute must return the type.
The href attribute must return the location.
The ownerNode attribute must return the owner node.
The parentStyleSheet attribute must return the
parent CSS style sheet.
The title attribute must return the title or null if
title is the empty string.
The media attribute must return the media.
The disabled attribute, on getting, must return true if the
disabled flag
is set, or false otherwise. On setting, the {{StyleSheet/disabled}} attribute must set the
disabled flag if the new value is true, or unset the
disabled flag otherwise.
### The {{CSSStyleSheet}} Interface ### {#the-cssstylesheet-interface}
The {{CSSStyleSheet}} interface represents a CSS style sheet.
[Exposed=Window]
interface CSSStyleSheet : StyleSheet {
constructor(optional CSSStyleSheetInit options = {});
readonly attribute CSSRule? ownerRule;
[SameObject] readonly attribute CSSRuleList cssRules;
unsigned long insertRule(CSSOMString rule, optional unsigned long index = 0);
undefined deleteRule(unsigned long index);
Promise<CSSStyleSheet> replace(USVString text);
undefined replaceSync(USVString text);
};
dictionary CSSStyleSheetInit {
DOMString baseURL = null;
(MediaList or DOMString) media = "";
boolean disabled = false;
};
The ownerRule 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 attribute must follow these steps:
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 {{CSSStyleSheet/insertRule()}} or {{CSSStyleSheet/deleteRule()}} methods can result in
mutations reflected in the returned object.
The insertRule(rule, index) method must run the following steps:
The replaceSync(text) method must run the
steps to synchronously replace the rules of a CSSStyleSheet on this {{CSSStyleSheet}} given text.
To synchronously replace the rules of a CSSStyleSheet on sheet given text, run these steps:
#### Deprecated CSSStyleSheet members #### {#legacy-css-style-sheet-members}
Note: These members are required for compatibility with existing sites.
partial interface CSSStyleSheet {
[SameObject] readonly attribute CSSRuleList rules;
long addRule(optional DOMString selector = "undefined", optional DOMString style = "undefined", optional unsigned long index);
undefined removeRule(optional unsigned long index = 0);
};
The rules attribute must follow the same steps as {{CSSStyleSheet/cssRules}}, and return the same object {{CSSStyleSheet/cssRules}} would return.
The removeRule(index) method must run the same steps as {{CSSStyleSheet/deleteRule()}}.
The addRule(selector, block, optionalIndex) method must run the following steps:
Let rule be an empty string.
Append selector to rule.
Append " { " to rule.
If block is not empty, append block, followed by a space, to rule.
Append "}" to rule
Let index be optionalIndex if provided, or the number of CSS rules in the stylesheet otherwise.
Call {{CSSStyleSheet/insertRule()}}, with rule and index as arguments.
Return -1.
Authors should not use these members
and should instead use and teach the standard {{CSSStyleSheet}} interface defined earlier,
which is consistent with {{CSSGroupingRule}}.
CSS Style Sheet Collections {#css-style-sheet-collections}
----------------------------------------------------------
Below various new concepts are defined that are associated with each
{{DocumentOrShadowRoot}} object.
Each {{DocumentOrShadowRoot}} has an associated list of zero or more CSS style sheets, named the
document or shadow root CSS style sheets. This is
an ordered list that contains:
Any CSS style sheets created from HTTP Link headers, in header order
Each {{DocumentOrShadowRoot}} has an associated list of zero or more CSS style sheets, named the
final CSS style sheets. This is
an ordered list that contains:
A last CSS style sheet set name
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
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
with name name, run these steps:
[Exposed=Window]
interface StyleSheetList {
getter CSSStyleSheet? 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) 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 attribute must return the number of CSS style sheets
represented by the collection.
### Extensions to the {{DocumentOrShadowRoot}} Interface Mixin ### {#extensions-to-the-document-or-shadow-root-interface}
The styleSheets attribute must return a {{StyleSheetList}} collection representing
the document or shadow root CSS style sheets.
The [=observable array attribute/set an indexed value=] algorithm for
adoptedStyleSheets, given value and index,
is the following:
Style Sheet Association {#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".
### Fetching CSS style sheets ### {#fetching-css-style-sheets}
To fetch a CSS style sheet
with parsed URL parsed URL,
referrer referrer,
document document,
optionally a set of parameters parameters
(used as input to creating a request),
and an algorithm for handling the response result processTheResponse that takes a response,
follow these steps:
### The {{LinkStyle}} Interface ### {#the-linkstyle-interface}
The associated CSS style sheet of a node is the CSS style sheet in the list of
document or shadow root CSS style sheets of which the owner node is said node.
This node must also implement the {{LinkStyle}} interface.
In the following fragment, the first <{style}>
element has a {{LinkStyle/sheet}} attribute that returns a
{{StyleSheet}} object representing the style sheet, but for
the second <{style}> element, the {{LinkStyle/sheet}} attribute returns null,
assuming the user agent supports CSS (text/css), but does
not support the (hypothetical) ExampleSheets (text/example-sheets).
<style type="text/css">
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.
### Requirements on specifications ### {#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.
### Requirements on user agents Implementing the xml-stylesheet processing instruction ### {#requirements-on-user-agents-implementing-the-xml-stylesheet-processing-instruction}
ProcessingInstruction includes LinkStyle;
The prolog refers to nodes that are children of the
document and are not following the
{{Element}} child of the document, if any.
When a ProcessingInstructionnodenode becomes part of the
prolog, is no longer part of the prolog, or has its data changed, these steps
must be run:
If an instance of this algorithm is currently running for node, abort that instance, and stop the associated
fetching if applicable.
Let parsed URL be the return value of invoking the URL parser with the
string input URL and the base URL base URL.
If parsed URL is failure, then return.
[=Fetch a CSS style sheet=]
with parsed URL parsed URL,
referrer referrer,
document document,
and processTheResponse given |response| being the following steps:
If the element has a charsetpseudo-attribute,
get an encoding from that pseudo-attribute's value.
If that succeeds, return the resulting encoding and abort these steps.
Let parsed URL be the return value of invoking the URL parser with the
string input URL and the base URL base URL.
If parsed URL is failure, then return.
[=Fetch a CSS style sheet=]
with parsed URL parsed URL,
referrer referrer,
document being the document,
and processTheResponse, given |response|, being the following steps:
Issue: What if the HTML parser hasn't decided on quirks/non-quirks yet?
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 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.
CSS Rules {#css-rules}
----------------------
A CSS rule 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
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
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
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
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 from a string string, run the following steps:
Let rule be the return value of invoking parse a rule with string.
If rule is a syntax error, return rule.
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 rule is dropped, return a syntax error.
Return parsed rule.
To serialize a CSS rule, perform one of the following in accordance with the CSS rule's
type:
{{CSSStyleRule}}
Return the result of the following steps:
Let |s| initially be
the result of performing serialize a group of selectors on the rule's associated selectors,
followed by the string " {", i.e., a single SPACE (U+0020), followed by LEFT CURLY BRACKET (U+007B).
Let |decls| be the result of performing serialize a CSS declaration block on the rule's associated declarations, or null if there are no such declarations.
Let |rules| be the result of performing [=serialize a CSS rule=] on each rule in the rule's {{CSSStyleRule/cssRules}} list, or null if there are no such rules.
If |decls| and |rules| are both null, append " }" to |s| (i.e. a single SPACE (U+0020) followed by RIGHT CURLY BRACKET (U+007D)) and return |s|.
If |rules| is null:
Append a single SPACE (U+0020) to |s|
Append |decls| to |s|
Append " }" to |s| (i.e. a single SPACE (U+0020) followed by RIGHT CURLY BRACKET (U+007D)).
Return |s|.
Otherwise:
If |decls| is not null, prepend it to |rules|.
For each |rule| in |rules|:
Append a newline followed by two spaces to |s|.
Append |rule| to |s|.
Append a newline followed by RIGHT CURLY BRACKET (U+007D) to |s|.
Return |s|.
{{CSSImportRule}}
The result of concatenating the following:
The string "@import" followed by a single SPACE (U+0020).
The result of performing serialize a URL on the rule's location.
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.
The string ";", i.e., SEMICOLON (U+003B).
@import url("import.css");
@import url("print.css") print;
{{CSSMediaRule}}
The result of concatenating the following:
The string "@media", followed by a single SPACE (U+0020).
A single SPACE (U+0020), followed by the string "{", i.e., LEFT CURLY BRACKET (U+007B), followed by a newline.
The result of performing serialize a CSS rule on each rule in the rule's {{CSSGroupingRule/cssRules}} list, separated by a newline and indented by two spaces.
A newline, followed by the string "}", i.e., RIGHT CURLY BRACKET (U+007D)
{{CSSFontFaceRule}}
The result of concatenating the following:
The string "@font-face {", followed by a single SPACE (U+0020).
The string "font-family:", followed by a single SPACE (U+0020).
The result of performing serialize a string on the rule’s font family name.
The string ";", i.e., SEMICOLON (U+003B).
If the rule's associated source list is not empty, follow these substeps:
A single SPACE (U+0020), followed by the string "src:", followed by a single
SPACE (U+0020).
If rule's associated 'unicode-range' descriptor is present, a single
SPACE (U+0020), followed by the string "unicode-range:", followed by a single SPACE
(U+0020), followed by the result of performing serialize a <<'unicode-range'>>, followed by the
string ";", i.e., SEMICOLON (U+003B).
If rule's associated 'font-variant' descriptor is present, a single
SPACE (U+0020), followed by the string "font-variant:", followed by a single SPACE
(U+0020), followed by the result of performing serialize a <<'font-variant'>>, followed by the
string ";", i.e., SEMICOLON (U+003B).
If rule's associated 'font-feature-settings' descriptor is present, a
single SPACE (U+0020), followed by the string "font-feature-settings:", followed by
a single SPACE (U+0020), followed by the result of performing serialize a
<<'font-feature-settings'>>, followed by the string ";", i.e., SEMICOLON
(U+003B).
If rule's associated 'font-stretch' descriptor is present, a single
SPACE (U+0020), followed by the string "font-stretch:", followed by a single SPACE
(U+0020), followed by the result of performing serialize a <<'font-stretch'>>, followed by the
string ";", i.e., SEMICOLON (U+003B).
If rule's associated 'font-weight' descriptor is present, a single SPACE
(U+0020), followed by the string "font-weight:", followed by a single SPACE
(U+0020), followed by the result of performing serialize a <<'font-weight'>>, followed by the
string ";", i.e., SEMICOLON (U+003B).
If rule's associated 'font-style' descriptor is present, a single SPACE
(U+0020), followed by the string "font-style:", followed by a single SPACE (U+0020),
followed by the result of performing serialize a <<'font-style'>>, followed by the string
";", i.e., SEMICOLON (U+003B).
A single SPACE (U+0020), followed by the string "}", i.e., RIGHT CURLY BRACKET (U+007D).
Issue: Need to define how the {{CSSFontFaceRule}} descriptors' values are serialized.
{{CSSPageRule}}
Issue: Need to define how {{CSSPageRule}} is serialized.
{{CSSNamespaceRule}}
The literal string "@namespace", followed by a single SPACE
(U+0020), followed by the
serialization as an identifier of the
{{CSSNamespaceRule/prefix}} attribute (if
any), followed by a single SPACE (U+0020) if there is a prefix, followed by the
serialization as URL of the
{{CSSNamespaceRule/namespaceURI}}
attribute, followed the character ";" (U+003B).
{{CSSKeyframesRule}}
The result of concatenating the following:
The literal string "@keyframes", followed by a single SPACE (U+0020).
The serialization of the {{CSSKeyframesRule/name}} attribute. If the attribute is a CSS wide keyword, or the value ''default'', or the value ''none'',
then it is serialized as a string. Otherwise, it is serialized as an identifier.
The string " { ", i.e., a single SPACE (U+0020), followed by LEFT CURLY BRACKET (U+007B), followed by a single SPACE (U+0020).
The result of performing serialize a CSS rule on each rule in the rule's {{CSSKeyframesRule/cssRules}} list, separated by a newline and indented by two spaces.
A newline, followed by the string "}", i.e., RIGHT CURLY BRACKET (U+007D)
{{CSSKeyframeRule}}
The result of concatenating the following:
The {{CSSKeyframeRule/keyText}}.
The string " { ", i.e., a single SPACE (U+0020), followed by LEFT CURLY BRACKET (U+007B), followed by a single SPACE (U+0020).
If the rule is associated with one or more declarations, the string "", i.e., a single SPACE (U+0020).
The string "}", RIGHT CURLY BRACKET (U+007D).
Issue: The "indented by two spaces" bit matches browsers, but needs work, see #5494
To insert a CSS rule rule in a CSS rule list list at index index, follow these steps:
Set length to the number of items in list.
If index is greater than length, then throw
an {{IndexSizeError}} exception.
Set new rule to the results of performing parse a CSS rule
on argument rule.
If new rule is a syntax error, throw
a {{SyntaxError}} exception.
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.
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.
Insert new rule into list at the zero-indexed position index.
Return index.
To remove a CSS rule from a CSS rule list list at index index, follow these steps:
Set length to the number of items in list.
If index is greater than or equal to length, then throw
an {{IndexSizeError}} exception.
Set old rule to the indexth item in list.
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.
Remove rule old rule from list at the zero-indexed position index.
### The {{CSSRuleList}} Interface ### {#the-cssrulelist-interface}
The {{CSSRuleList}} interface represents an ordered collection of [=CSS rules=].
[Exposed=Window]
interface CSSRuleList {
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) 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 attribute must return the number of {{CSSRule}} objects represented by the
collection.
### The {{CSSRule}} Interface ### {#the-cssrule-interface}
The {{CSSRule}} interface represents an abstract, base [=CSS rule=]. Each
distinct CSS rule type is represented by a distinct interface that
inherits from this interface.
[Exposed=Window]
interface CSSRule {
attribute CSSOMString cssText;
readonly attribute CSSRule? parentRule;
readonly attribute CSSStyleSheet? parentStyleSheet;
// the following attribute and constants are historical
readonly attribute unsigned short type;
const unsigned short STYLE_RULE = 1;
const unsigned short CHARSET_RULE = 2;
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;
};
The cssText attribute must return a serialization of the
CSS rule.
On setting the {{CSSRule/cssText}} attribute must do nothing.
The parentRule attribute must return the parent CSS
rule.
Note: For example, @media can enclose a rule, in which case {{CSSRule/parentRule}} would
be non-null; in cases where there is no enclosing rule, {{CSSRule/parentRule}} will be null.
The parentStyleSheet 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.
The type attribute is deprecated.
It must return an integer, as follows:
If the object is a {{CSSStyleRule}}
Return 1.
If the object is a {{CSSImportRule}}
Return 3.
If the object is a {{CSSMediaRule}}
Return 4.
If the object is a {{CSSFontFaceRule}}
Return 5.
If the object is a {{CSSPageRule}}
Return 6.
If the object is a {{CSSKeyframesRule}}
Return 7.
If the object is a {{CSSKeyframeRule}}
Return 8.
If the object is a {{CSSMarginRule}}
Return 9.
If the object is a {{CSSNamespaceRule}}
Return 10.
If the object is a {{CSSCounterStyleRule}}
Return 11.
If the object is a {{CSSSupportsRule}}
Return 12.
If the object is a {{CSSFontFeatureValuesRule}}
Return 14.
Otherwise
Return 0.
Note: The practice of using an integer enumeration
and several constants to identify the integers
is a legacy design practice that is no longer used in Web APIs.
Instead, to tell what type of rule a given object is,
it is recommended to check rule.constructor.name,
which will return a string like "CSSStyleRule".
This enumeration is thus frozen in its current state,
and no new new values will be added to reflect additional at-rules;
all at-rules beyond the ones listed above will return 0.
### The {{CSSStyleRule}} Interface ### {#the-cssstylerule-interface}
The CSSStyleRule interface represents a style rule.
The selectorText attribute, on getting, must return the result of
serializing the associated group of selectors.
On setting the {{CSSStyleRule/selectorText}} attribute these steps must be run:
The specified order 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]]
### The {{CSSImportRule}} Interface ### {#the-cssimportrule-interface}
The CSSImportRule interface represents an @import at-rule.
The href attribute must return the URL specified by
the @import at-rule.
Note: To get the resolved URL use the {{StyleSheet/href}}
attribute of the associated CSS style sheet.
The media attribute must return the value of the {{StyleSheet/media}}
attribute of the associated CSS style sheet.
The styleSheet attribute must return the associated CSS style sheet, if any, or null otherwise.
The layerName attribute must return the [=layer name=] declared in the at-rule itself,
or an empty string if the layer is anonymous,
or null if the at-rule does not declare a layer.
The supportsText attribute must return the <> declared in the at-rule itself,
or null if the at-rule does not declare a supports condition.
Note: An @import at-rule might not have an associated CSS style sheet (e.g., if it has a non-matching supports() condition).
### The {{CSSGroupingRule}} Interface ### {#the-cssgroupingrule-interface}
The CSSGroupingRule interface represents an at-rule that contains other rules nested inside itself.
[Exposed=Window]
interface CSSGroupingRule : CSSRule {
[SameObject] readonly attribute CSSRuleList cssRules;
unsigned long insertRule(CSSOMString rule, optional unsigned long index = 0);
undefined deleteRule(unsigned long index);
};
The cssRules attribute must return a CSSRuleList object for the
child CSS rules.
The insertRule(rule, index) method must return the result of
invoking insert a CSS rulerule into the child CSS rules at
index.
The deleteRule(index) method must remove a CSS rule from the
child CSS rules at index.
### The {{CSSMediaRule}} Interface ### {#the-cssmediarule-interface}
The {{CSSMediaRule}} interface is defined in CSS Conditional Rules.
[[!CSS3-CONDITIONAL]]
### The {{CSSPageRule}} Interface ### {#the-csspagerule-interface}
The CSSPageRule interface represents an @page at-rule.
Issue: Need to define the rules for
parse a list of CSS page selectors and
serialize a list of CSS page selectors.
The selectorText attribute, on getting, must return the result of
serializing the associated list of CSS page selectors.
On setting the {{CSSPageRule/selectorText}} attribute these steps must be run:
### The {{CSSMarginRule}} Interface ### {#the-cssmarginrule-interface}
The CSSMarginRule interface represents a margin at-rule (e.g. @top-left) in an @page at-rule.
[[!CSS3PAGE]]
The name attribute must return the name of the margin at-rule. The @ character is not
included in the name. [[!CSS3SYN]]
The style attribute must return a CSSMarginDescriptors object for the
margin at-rule, with the following properties:
The namespaceURI attribute must return the namespace of the
@namespace at-rule.
The prefix attribute must return the prefix of the @namespace at-rule or the
empty string if there is no prefix.
CSS Declarations {#css-declarations}
------------------------------------
A CSS declaration is an abstract concept that is not exposed as an object in the DOM. A CSS declaration has the following associated
properties:
property name
The property name of the declaration.
value
The value of the declaration represented as a list of component values.
important flag
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.
CSS Declaration Blocks {#css-declaration-blocks}
------------------------------------------------
A CSS declaration block 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:
computed flag
Set if the object is a computed style declaration, rather than a specified
style. Unless otherwise stated it is unset.
To parse a CSS declaration block from a string string, follow these steps:
Let declarations be the returned declarations from invoking parse a block's contents with string.
Let parsed declarations be a new empty list.
For each item declaration in declarations, follow these substeps:
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.
If parsed declaration is not null, append it to parsed declarations.
Return parsed declarations.
To serialize a CSS declaration with property name property, value value and optionally an important flag set, follow
these steps:
Let s be the empty string.
Append property to s.
Append ": " (U+003A U+0020) to s.
Append value to s.
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.
Append ";" (U+003B) to s.
Return s.
To serialize a CSS declaration block declaration block means to run the steps below:
Let list be an empty array.
Let already serialized be an empty array.
Declaration loop: For each CSS declarationdeclaration in declaration block's
declarations, follow these substeps:
If property is in already serialized, continue with the steps labeled declaration loop.
If property maps to one or more shorthand properties, let shorthands be an array of those shorthand properties, in
preferred order.
Shorthand loop: For each shorthand in shorthands, follow these substeps:
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.
If all properties that map to shorthand are not present in longhands, continue with the steps labeled shorthand loop.
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.
If there's any declaration in declaration block in between the first and the last longhand in current longhands
which belongs to the same [=logical property group=], but has a different [=mapping logic=] as any of the longhands in current longhands,
and is not in current longhands, continue with the steps labeled shorthand loop.
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.
Append serialized declaration to list.
Append property to already serialized.
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.
A CSS declaration block has these attribute change steps for its owner node
with localName, value, and namespace:
The preferred order of a list of shorthand properties shorthands is as follows:
Order shorthands lexicographically.
Move all items in shorthands that begin with "-" (U+002D) last in the list, retaining their relative order.
Move all items in shorthands that begin with "-" (U+002D) but do not begin with "-webkit-" last in the
list, retaining their relative order.
Order shorthands by the number of longhand properties that map to it, with the greatest number first.
### The {{CSSStyleDeclaration}} Interface ### {#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.
The length attribute must return the number of CSS
declarations in the declarations.
The item(index) method must return the
property name of the CSS declaration at position index.
The getPropertyValue(property) method must run these steps:
If property is not a custom property, follow these substeps:
If property is a shorthand property, follow these substeps:
Let list be a new array.
For each longhand property longhand that property maps to, append the result of invoking
{{CSSStyleDeclaration/getPropertyPriority()}} with longhand as argument to list.
If all items in list are the string "important", then return the string "important".
If value is the empty string, invoke {{CSSStyleDeclaration/removeProperty()}}
with property as argument and return.
If priority is not the empty string and is not an ASCII case-insensitive match for the string
"important", then return.
Let component value list be the result of parsingvalue for property property.
Note: value can not include "!important".
If component value list is null, then return.
Let updated be false.
If property is a shorthand property, then for each longhand property longhand that property maps to, in canonical
order, follow these substeps:
Let longhand result be the result of set the CSS declarationlonghand 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.
If longhand result is true, let updated be true.
Otherwise, let updated be the result of set the CSS declarationproperty 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 property with a value component value list and optionally with an important flag set, in
a list of declarations declarations, the user agent must ensure the following constraints hold after its steps:
Exactly one CSS declaration whose property name is a
case-sensitive match of property must exist in declarations.
Such declaration is referenced as the target declaration below.
The target declaration must have value being component value list,
and target declaration's important flag must be
set if important flag is set, and unset otherwise.
Any CSS declaration which is not the target declaration must not be changed, inserted,
or removed from declarations.
The steps must return true if the serialization of declarations was changed as result
of the steps. It may return false otherwise.
Issue: Should we add something like "Any observable side effect must not be made outside
declarations"? The current constraints sound like a hole for undefined behavior.
Note: The steps of set a CSS declaration are not defined in this level of CSSOM. User agents may
use different algorithms as long as the constraints above hold.
The simplest way to conform with the constraints would be to always remove any existing declaration
matching property, and append the new declaration to the end. But based on implementation
feedback, this approach would likely regress performance.
Another possible algorithm is:
The parentRule attribute must return the
parent CSS rule.
The cssFloat
attribute, on getting, must return the result of invoking
{{CSSStyleDeclaration/getPropertyValue()}} with
float as argument. On setting, the attribute must invoke
{{CSSStyleDeclaration/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.
The camel-cased attribute attribute, on getting, must return the
result of invoking {{CSSStyleDeclaration/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
{{CSSStyleDeclaration/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 example, for the 'font-size' property there would be a fontSize IDL attribute.
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.
The webkit-cased attribute attribute, on
getting, must return the result of invoking {{CSSStyleDeclaration/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 {{CSSStyleDeclaration/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 example, if the user agent supports the '-webkit-transform' property, there
would be a webkitTransform IDL attribute. There would also be a
WebkitTransform IDL attribute because of the rules for camel-cased attributes.
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.
The dashed attribute attribute, on getting, must return the
result of invoking {{CSSStyleDeclaration/getPropertyValue()}} with the
argument being dashed attribute.
Setting the dashed attribute attribute must invoke
{{CSSStyleDeclaration/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.
For example, for the 'font-size' property there would be a font-size IDL attribute. In JavaScript, the property can be accessed as
follows, assuming element is an HTML element:
element.style['font-size'];
The CSS property to IDL attribute algorithm for property, optionally with a
lowercase first flag set, is as follows:
Let output be the empty string.
Let uppercase next be unset.
If the lowercase first flag is set, remove the first character from property.
For each character c in property:
If c is "-" (U+002D), let uppercase next be set.
Otherwise, if uppercase next is set, let uppercase next be unset and append cconverted to ASCII uppercase to output.
Otherwise, append c to output.
Return output.
The IDL attribute to CSS property algorithm for attribute, optionally with a
dash prefix flag set, is as follows:
Let output be the empty string.
If the dash prefix flag is set, append "-" (U+002D) to output.
For each character c in attribute:
If c is in the range U+0041 to U+005A (ASCII uppercase), append "-" (U+002D) followed by cconverted to ASCII lowercase to output.
Otherwise, append c to output.
Return output.
CSS Values {#css-values}
------------------------
### Parsing CSS Values ### {#parsing-css-values}
To parse a CSS value value for a given
property means to follow these steps:
Match list against the grammar for the property property in the CSS specification.
If the above step failed, return null.
Return list.
Note: "!important" declarations are not
part of the property value space and will therefore cause
parse a CSS value to return null.
### Serializing CSS Values ### {#serializing-css-values}
To serialize a CSS value 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|:
1. Let |shorthand| be the first shorthand property,
in [=preferred order=],
that exactly maps to all of the longhand properties in |list|.
2. If there is no such shorthand or
|shorthand| cannot exactly represent the values of all the properties in |list|,
return the empty string.
3. Otherwise, [=serialize a CSS value=]
from a hypothetical declaration of the property |shorthand|
with its value representing the combined values of the declarations in |list|.
2. Represent the value of the |declaration|
as a [=list=] of CSS component values |components|
that, when [=CSS/parsed=] according to the property's grammar,
would represent that value.
Additionally:
* If certain component values can appear in any order
without changing the meaning of the value
(a pattern typically represented by a double bar || in the value syntax),
reorder the component values to use the canonical order of component values
as given in the property definition table.
* If component values can be omitted or replaced with a shorter representation
without changing the meaning of the value,
omit/replace them.
* If either of the above syntactic translations would be less backwards-compatible,
do not perform them.
Note: The rules described here outlines the general principles of serialization.
For legacy reasons, some properties serialize in a different manner,
which is intentionally undefined here due to lack of resources.
Please consult your local reverse-engineer for details.
3. Remove any <>s from |components|.
3. Replace each component value in |components|
with the result of invoking [=serialize a CSS component value=].
4. Join the items of |components| into a single string,
inserting " " (U+0020 SPACE) between each pair of items
unless the second item is a "," (U+002C COMMA)
Return the result.
To
serialize a CSS component value
depends on the component, as follows:
The <number> component serialized as per <number> followed by the unit in canonical form as defined in its respective specification.
Issue: Probably should distinguish between declared and computed / resolved values.
<>
If <color> is a component of a resolved value, see [[css-color-4#resolving-color-values]].
If <color> is a component of a computed value, see [[css-color-4#serializing-color-values]].
If <> is a component of a declared value, then
for sRGB values, see
[[css-color-4#resolving-sRGB-values]].
For other color functions, see
[[css-color-4#resolving-color-values]].
<>
See [[css-color-4#serializing-alpha-values]].
<>
The return value of the following algorithm:
Let s be the empty string.
If <counter> has three CSS component values append the string
"counters(" to s.
If <counter> has two CSS component values append the string
"counter(" to s.
Let list be a list of CSS component values belonging to <counter>, omitting the last CSS component value if it is "decimal".
The <number> component serialized as per <number> followed by the unit in its canonical form as defined in its respective specification.
Issue: Probably should distinguish between declared and computed / resolved values.
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.
<>
The <number> component serialized as per <number> followed by the unit in its canonical form as defined in its respective specification.
Issue: Probably should distinguish between declared and computed / resolved values.
<>
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.
<>
The <number> component serialized as per <number> followed
by the literal string "%" (U+0025).
<>
The resolution in dots per CSS pixel serialized as per
<number> followed by the literal string "dppx".
<>
The numerator serialized as per <number>
followed by the literal string " / ",
followed by the denominator serialized as per <number>.
<>
The return value of the following algorithm:
Let s be the string "rect(".
Let list be a list of the CSS component values belonging to <shape>.
<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.
Issue: 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.
#### Examples #### {#serializing-css-values-examples}
Here are some examples of before and after results on declared 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.
Before
After
background: none
background: rgba(0, 0, 0, 0)
outline: none
outline: invert
border: none
border: medium
list-style: none
list-style: disc
margin: 0 1px 1px 1px
margin: 0px 1px 1px
azimuth: behind left
azimuth: 220deg
font-family: a, 'b"', serif
font-family: "a", "b\"", serif
content: url('h)i') '\[\]'
content: url("h)i") "[]"
azimuth: leftwards
azimuth: leftwards
color: rgb(18, 52, 86)
color: #123456
color: rgba(000001, 0, 0, 1)
color: #000000
Issue: Some of these need to be updated per the new rules.
DOM Access to CSS Declaration Blocks {#dom-access-to-css-declaration-blocks}
============================================================================
The {{ElementCSSInlineStyle}} Mixin
The ElementCSSInlineStyle mixin provides access to inline style properties of an element.
If the user agent supports SVG, the following IDL applies: [[SVG11]]
SVGElement includes ElementCSSInlineStyle;
If the user agent supports MathML, the following IDL applies: [[MathML-Core]]
MathMLElement includes ElementCSSInlineStyle;
Extensions to the {{Window}} Interface {#extensions-to-the-window-interface}
----------------------------------------------------------------------------
The {{Window/getComputedStyle()}} method exposes information from CSS style
sheets with the origin-clean flag unset.
Issue: Should getComputedStyle() provide a useful serialization?
See #1033
Utility APIs {#utility-apis}
============================
The CSS.escape() Method {#the-css.escape()-method}
------------------------------------------------------
The CSS namespace holds useful CSS-related functions that do not belong elsewhere.
Issue: This was previously specified as an IDL interface
that only held static methods.
Switching to an IDL namespace is *nearly* identical,
so it's expected that there won't be any compat concerns.
If any are discovered, please report
so we can consider reverting this change.
The escape(ident) operation must return the result of invoking serialize an identifier of
ident.
For example, to serialize a string for use as part of a selector, the {{CSS/escape()}} method can be used:
var element = document.querySelector('#' + CSS.escape(id) + ' > img');
The {{CSS/escape()}} method can also be used for escaping strings, although it escapes characters that don't strictly need to be
escaped:
var element = document.querySelector('a[href="#' + CSS.escape(fragment) + '"]');
Specifications that define operations on the {{CSS}} namespace and want to
store some state should store the state on the current global
object's associated Document.
Resolved Values {#resolved-values}
==================================
{{Window/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
{{Window/getComputedStyle()}} had to
remain the same for compatibility with deployed scripts. To address this
issue this specification introduces the concept of a
resolved value.
The resolved value for a given longhand property can be determined
as follows:
'background-color'
'border-block-end-color'
'border-block-start-color'
'border-bottom-color'
'border-inline-end-color'
'border-inline-start-color'
'border-left-color'
'border-right-color'
'border-top-color'
'box-shadow'
'caret-color'
'color'
'outline-color'
A resolved value special case property like 'color' defined in another specification
A resolved value special case property like 'top' defined in another specification
If the property applies to a positioned element and the resolved value of the 'display'
property is not ''display/none'' or ''display/contents'', and the property is not over-constrained,
then the resolved value is the used value. Otherwise the resolved value is the
computed value.
A resolved value special case property defined in another specification
IANA Considerations {#iana-considerations}
==========================================
Default-Style {#default-style}
------------------------------------------------------------------------------------
This section describes a header field for registration in the Permanent
Message Header Field Registry.
Header field name
Default-Style
Applicable protocol
http
Status
standard
Author/Change controller
W3C
Specification document(s)
This document is the relevant specification.
Related information
None.
Change History {#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.
Changes From 17 March 2016 {#changes-from-17-march-2016}
------------------------------------------------------------
* Serialization of <> is changed.
* [CEReactions] IDL extended attributes are added.
* Resolved value for logical properties are added.
* getComputedStyle for 'display': ''display/contents'' is changed.
* MediaList.item now returns serialization.
* MediaList.item does not serialize shorthand if importance differs.
* Other specifications are allowed to specify resolved value.
* index argument in insertRule is now optional.
* href attribute of Stylesheet and CSSImportRule now uses USVString.
* CSSOMString is introduced.
* Serialization of CSSMediaRule and CSSFontFaceRule is added.
* Updating flag is added to CSS declaration block to avoid serialize-and-reparse on style attribute.
* Serialization of a declaration value is now properly defined.
* getComputedStyle now returns the style rules of the node's document.
* A {{TypeError}} is thrown when the pseudo-element passed to getComputedStyle is unknown or ''::slotted()''.
* {{CSS}} is switched from interface to namespace.
* setPropertyValue and setPropertyPriority are removed from {{CSSStyleDeclaration}} due to lack of interest from implementations.
* The styleSheets IDL attribute is moved from {{Document}} to {{DocumentOrShadowRoot}}.
* LinkStyle.sheet now returns CSSStyleSheet instead of StyleSheet
* Deprecated CSSStyleSheet members are defined.
* The CSSRule.type attribute is deprecated.
* Serialization of <> is added.
* CSSStyleDeclaration.cssText now returns the empty string for computed style.
* Custom properties are included in getComputedStyle.
* MathML IDL is introduced.
* Serialization of {{CSSKeyframesRule}} and {{CSSKeyframeRule}} is added.
* Serialization of media query is changed.
* A shorthand is not serialized if there are longhands with other property group / mapping logic in between the longhands of that shorthand.
* {{CSSStyleRule}} serialization is aware of nesting now.
* Constructable stylesheets is introduced.
Changes From 5 December 2013 {#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 {{CSSRule/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 {{CSSStyleSheet/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 <> and <> is changed.
* {{CSSStyleDeclaration/setProperty()}} on {{CSSStyleDeclaration}} is changed.
Changes From 12 July 2011 To 5 December 2013 {#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 {{CSSStyleDeclaration/setProperty()}},
{{CSSStyleDeclaration/getPropertyValue()}}, et al.
setPropertyValue and setPropertyPriority are added to {{CSSStyleDeclaration}}.
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.
Security and Privacy Considerations
===================================
No new security or privacy considerations have been reported on this specification.
Acknowledgments {#acknowledgments}
==================================
The editors would like to thank
Alexey Feldgendler,
Benjamin Poulain,
Björn Höhrmann,
Boris Zbasky,
Brian Kardell,
Chris Dumez,
Christian Krebs,
Daniel Glazman,
David Baron,
Domenic Denicola,
Dominique Hazael-Massieux,
fantasai,
Hallvord R. M. Steen,
Ian Hickson,
John Daggett,
Lachlan Hunt,
Mike Sherov,
Myles C. Maxfield,
Morten Stenshorne,
Ms2ger,
Nazım Can Altınova,
Øyvind Stenhaug,
Peter Sloetjes,
Philip Jägenstedt,
Philip Taylor,
Richard Gibson,
Robert O'Callahan,
Simon Sapin,
Sjoerd Visscher,
Sylvain Galineau,
Tarquin Wilton-Jones,
Xidorn Quan, 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.