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/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
Work Status: Exploring
Shortname: cssom
Level: 1
Editor: Daniel Glazman, Disruptive Innovations http://disruptive-innovations.com/, daniel.glazman@disruptive-innovations.com, w3cid 13329
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.
Ignored Terms: EmptyString, mediaText, cssText, InvalidCharacterError, SecurityError, SyntaxError, IndexSizeError, HierarchyRequestError, InvalidStateError, InvalidModificationError, NoModificationAllowedError, CORS-same-origin, group of selectors, list of css page selectors, CSSCharsetRule, ProcessingInstruction, EventTarget, EventListener, Event, EventInit, Element, Range, Node, Text, style, CSSFontFaceRule, -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: document base url
text: content-type metadata; url: #content-type
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: style sheet ready
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
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
spec:css-display-3; type:value; for:display; text:table
spec:css-color-4; type:property; text:color
spec:css-position-3; type:property; text:left
spec:html5; type:element; text:style
spec:css-namespaces-3; type:dfn; text:namespace prefix
spec:dom; type:interface; text:Document
spec:html; type:dfn; text:ascii case-insensitive
spec:html; type:dfn; text:case-sensitive
spec:css-logical; type:property; text:inline-size
spec:css-variables-1; type:dfn; text:custom property
spec:selectors-3; type:selector; text:::before
spec:selectors-3; type:selector; text:::after
spec:css-fonts-4; type:descriptor; text:unicode-range
spec:css-fonts-4; type:descriptor; text:font-variant
spec:css-fonts-4; type:descriptor; text:font-feature-settings
spec:css-fonts-4; type:descriptor; text:font-stretch
spec:css-fonts-4; type:descriptor; text:font-weight
spec:css-fonts-4; type:descriptor; text:font-style
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-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.
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.
- Otherwise, the escaped
character.
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 URL 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 the Media Queries specification. 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 list of
media queries, and then serialize the list.
To
serialize a media query let
s be the empty string, run the steps below:
- If the media query is negated append "
not", followed
by a single SPACE (U+0020), to s.
- Let type be the serialization
as an identifier of the media type of the media query,
converted to ASCII lowercase.
- If the media query does not contain media features append
type, to s,
then return s.
- If type is not "
all" or if the
media query is negated append type, followed by a
single SPACE (U+0020), followed by "and", followed by a single SPACE
(U+0020), to s.
- Sort the media features in lexicographical order.
-
Then, for each media feature:
- Append a "
(" (U+0028), followed by the media feature
name, converted to ASCII lowercase,
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 (max-width: 40px) and (min-width: 5px)
|
all and (color) and (color)
| (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.
[Exposed=Window,
LegacyArrayClass]
interface MediaList {
stringifier attribute [TreatNullAs=EmptyString] CSSOMString mediaText;
readonly attribute unsigned long length;
getter CSSOMString? item(unsigned long index);
void appendMedium(CSSOMString medium);
void deleteMedium(CSSOMString 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 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:
- Empty the collection of media queries.
- If the given value is the empty string, then return.
- Append all the media queries as a result of parsing the given
value to the collection of media queries.
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:
- Let m be the result of parsing the given value.
- If m is null, then return.
- If comparing m with any of the media queries in the
collection of media queries returns true, then return.
- Append m to the collection of media queries.
The deleteMedium(medium) method must run these steps:
- Let m be the result of parsing the given value.
- If m is null, then return.
- 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 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.
- 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.
- 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:
- type selector
- universal selector
-
- 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
serialization of the
namespace prefix as an identifier, followed by a
"
|" (U+007C) to 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.
:lang()
- The serialization of a
comma-separated list of each argument's
serialization as a string, preserving
relative order.
: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.
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. A
CSS style sheet has a number of associated state items:
- type
- The literal string "
text/css".
- location
- Specified when created. The absolute-URL string 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
- 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
- Specified when created. The DOM node associated with the CSS style sheet or
null if there is no associated DOM node.
- owner CSS rule
- 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
-
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.
- 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.
- alternate flag
-
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
-
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
- The CSS rules associated with the
CSS style sheet.
- origin-clean flag
- Specified when created. Either set or unset. If it is set, the API allows reading and modifying of the CSS rules.
### The {{StyleSheet}} Interface ### {#the-stylesheet-interface}
The {{StyleSheet}} interface represents an abstract, base style sheet.
[Exposed=Window]
interface StyleSheet {
readonly attribute CSSOMString type;
readonly attribute USVString? 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 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 {
readonly attribute CSSRule? ownerRule;
[SameObject] readonly attribute CSSRuleList cssRules;
unsigned long insertRule(CSSOMString rule, optional unsigned long index = 0);
void deleteRule(unsigned long index);
};
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:
- If the origin-clean flag is unset,
throw a {{SecurityError}} exception.
- 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:
- If the origin-clean flag is unset,
throw a {{SecurityError}} exception.
- Return the result of invoking insert a CSS rule rule in the CSS rules
at index.
The deleteRule(index) method must run the following steps:
- If the origin-clean flag is unset,
throw a {{SecurityError}} exception.
- Remove a CSS rule in the CSS rules at index.
CSS Style Sheet Collections {#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. 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, run these
steps:
- Create a new CSS style sheet object and set its
properties as specified.
-
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, run these
steps:
- 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.
- If the disabled flag is set, then return.
- 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.
-
If any of the following is true, then unset the
disabled flag and return:
- Set the disabled flag.
To remove a CSS style sheet, run these steps:
- Remove the CSS style sheet from the list of document CSS style sheets.
- 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 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 is the
title the CSS style sheet set has in
common.
An enabled CSS style sheet set is a
CSS style sheet set of which each CSS style sheet has
its disabled flag unset.
To enable a CSS style sheet set
with name name, run these steps:
- If name is the empty string, set the
disabled flag for each CSS style sheet
that is in a CSS style sheet set and return.
- 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
with name name, run these steps:
- enable a CSS style sheet set with name
name.
- Set last CSS style sheet set name to
name.
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:
- Let current be the preferred CSS style sheet set name.
- Set preferred CSS style sheet set name to
name.
- 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.
### The HTTP Default-Style Header ### {#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.
### The {{StyleSheetList}} Interface ### {#the-stylesheetlist-interface}
The {{StyleSheetList}} interface represents an ordered collection of CSS style sheets.
[Exposed=Window,
LegacyArrayClass]
interface StyleSheetList {
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) 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 {{Document}} Interface ### {#extensions-to-the-document-interface}
partial interface Document {
[SameObject] readonly attribute StyleSheetList styleSheets;
};
The styleSheets attribute must return a {{StyleSheetList}} collection representing
the document CSS style sheets.
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), follow these steps:
- Let origin be document's origin.
- Let request be a new request, with the
url parsed URL,
origin origin,
referrer referrer, and if specified the set of parameters parameters.
- Let response be the result of fetching request.
- Wait until response is available.
- If response is a network error, return an error.
- 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.
- If response is not in a supported styling language return an error.
- Return response.
### The {{LinkStyle}} Interface ### {#the-linkstyle-interface}
The associated CSS style sheet 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.
[Exposed=Window,
NoInterfaceObject]
interface LinkStyle {
readonly attribute StyleSheet? sheet;
};
The sheet attribute must return the associated CSS style sheet for the node or null
if there is no associated CSS style sheet.
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>
<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.
### 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 implements 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 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:
- If an instance of this algorithm is currently running for node, abort that instance, and stop the associated
fetching if applicable.
- If node has an associated CSS style sheet, remove it.
- If node is not an xml-stylesheet processing instruction, then return.
- If node does not have an
href pseudo-attribute, then return.
- Let title be the value of the
title pseudo-attribute or the empty string if the
title pseudo-attribute is not specified.
- If there is an
alternate pseudo-attribute
whose value is a case-sensitive match
for "yes" and title is the
empty string, then return.
- If there is a
type pseudo-attribute whose
value is not a supported styling language the user agent
may return.
- Let input URL be the value specified by the
href pseudo-attribute.
- Let document be node's node document
- Let base URL be document's document base URL.
- Let referrer be document's address.
- 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.
- Let response be the result of fetching a CSS style sheet with parsed URL parsed URL,
referrer referrer and document document.
- If response is an error, then return.
-
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:
- 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.
- 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.
### Requirements on User Agents Implementing the HTTP Link Header ### {#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:
- Let title be the value of the first of all the
title parameters.
If there are no such parameters it is the empty string.
- If one of the (other) link relation types is an
ASCII case-insensitive match for
"
alternate" and title is the
empty string, then return.
- Let input URL be the value specified.
Issue: Be more specific
- Let base URL be the document's document base URL.
Issue: Is there a document at this point?
- Let referrer be the document's address.
- Let origin be the document's origin.
- 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.
- Let response be the result of fetching a CSS style sheet with parsed URL parsed URL,
referrer referrer and document being the document.
Issue: What if the HTML parser hasn't decided on quirks/non-quirks yet?
-
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.
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 style 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}}
-
The result of concatenating the following:
- The result of performing serialize a group of selectors on the rule's associated selectors.
- 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 declaration block on the rule's associated declarations.
- 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).
- {{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).
- The result of performing serialize a media query list on rule's media query list.
- 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 the each rule, seperated by a newline and indented by two spaces, in rule's CSSRules list.
- 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).
- The result of invoking serialize a comma-separated list on performing serialize a
URL or serialize a LOCAL for each source on the source list.
- The string "
;", i.e., SEMICOLON (U+003B).
- 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).
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.
- Set old rule's parent CSS rule and
parent CSS style sheet to null.
### The {{CSSRuleList}} Interface ### {#the-cssrulelist-interface}
The {{CSSRuleList}} interface represents an ordered collection of CSS style rules.
[Exposed=Window,
LegacyArrayClass]
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 style rule. Each
distinct CSS style rule type is represented by a distinct interface that
inherits from this interface.
[Exposed=Window]
interface CSSRule {
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 CSSOMString cssText;
readonly attribute CSSRule? parentRule;
readonly attribute CSSStyleSheet? parentStyleSheet;
};
The type attribute must return the CSS rule type, as follows:
- If the object is a {{CSSStyleRule}}
- Return STYLE_RULE (numeric value 1).
- If the object is a {{CSSImportRule}}
- Return IMPORT_RULE (numeric value 3).
- If the object is a {{CSSMediaRule}}
- Return MEDIA_RULE (numeric value 4).
- If the object is a {{CSSFontFaceRule}}
- Return FONT_FACE_RULE (numeric value 5).
- If the object is a {{CSSPageRule}}
- Return PAGE_RULE (numeric value 6).
- If the object is a {{CSSMarginRule}}
- Return MARGIN_RULE (numeric value 9).
- If the object is a {{CSSNamespaceRule}}
- Return NAMESPACE_RULE (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 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 {{CSSStyleRule}} Interface ### {#the-cssstylerule-interface}
The CSSStyleRule interface represents a style rule.
[Exposed=Window]
interface CSSStyleRule : CSSRule {
attribute CSSOMString selectorText;
[SameObject, PutForwards=cssText] readonly attribute CSSStyleDeclaration style;
};
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:
- Run the parse a group of selectors algorithm on the given value.
- If the algorithm returns a non-null value replace the associated group of selectors with the returned value.
- Otherwise, if the algorithm returns a null value, do nothing.
The style 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 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.
[Exposed=Window]
interface CSSImportRule : CSSRule {
readonly attribute USVString href;
[SameObject, PutForwards=mediaText] readonly attribute MediaList media;
[SameObject] readonly attribute CSSStyleSheet styleSheet;
};
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.
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.
### 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);
void 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 rule rule 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.
[Exposed=Window]
interface CSSPageRule : CSSGroupingRule {
attribute CSSOMString selectorText;
[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 {{CSSPageRule/selectorText}} attribute these steps must be run:
- Run the parse a list of CSS page selectors algorithm on the given value.
- If the algorithm returns a non-null value replace the associated list of CSS page selectors with the returned value.
- 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.
### The {{CSSMarginRule}} Interface ### {#the-cssmarginrule-interface}
The CSSMarginRule interface represents a margin at-rule (e.g. @top-left) in an @page at-rule.
[[!CSS3PAGE]]
[Exposed=Window]
interface CSSMarginRule : CSSRule {
readonly attribute CSSOMString name;
[SameObject, PutForwards=cssText] readonly attribute CSSStyleDeclaration style;
};
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 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.
### The {{CSSNamespaceRule}} Interface ### {#the-cssnamespacerule-interface}
The CSSNamespaceRule interface represents an @namespace at-rule.
[Exposed=Window]
interface CSSNamespaceRule : CSSRule {
readonly attribute CSSOMString namespaceURI;
readonly attribute CSSOMString prefix;
};
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:
- readonly flag
- Unset if the object can be manipulated. Set if it can not be
manipulated. Unless otherwise stated it is unset.
- declarations
- The CSS declarations associated with the object.
- parent CSS rule
- The CSS rule that the CSS declaration block is associated with, if any, or null otherwise.
- owner node
- The {{Element}} that the CSS declaration block is associated with, if any, or
null otherwise.
- updating flag
- Unset by default. Set when the CSS declaration block is updating
the owner node's
style attribute.
To parse a CSS declaration block from a string string, follow these steps:
- Let declarations be the return value of invoking parse a list of declarations 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 declaration declaration in declaration block's
declarations, follow these substeps:
- Let property be declaration's property name.
- 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, and 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.
- Shorthand loop: For each shorthand in shorthands, follow these substeps:
- If all properties that map to shorthand are not present in longhands, continue with the steps labeled shorthand loop.
- Let current longhands be an empty array.
- Append all CSS declarations in longhands have a
property name that maps to shorthand to current longhands.
- 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.
- Let value be the result of invoking serialize a CSS value of current longhands.
- If value is the empty string, continue with the steps labeled shorthand loop.
- 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.
- Append serialized declaration to list.
- Append the property names of all items of current longhands to already serialized.
- Remove the items present in current longhands from longhands.
- If property is in already serialized, continue with the steps labeled declaration loop.
- Let value be the result of invoking serialize a CSS value of declaration.
- 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:
- If the readonly flag is set, then return.
- If the updating flag is set, then return.
- If localName is not "
style", or namespace is not null, then return.
- If value is null, empty the declarations.
- Otherwise, let the declarations be the result of parse a CSS declaration block
from a string value.
When a CSS declaration block object is created, then:
- Let owner node be the owner node.
- If owner node is null, or the readonly flag is set, then return.
- Let value be the result of getting an attribute
given null, "
style", and owner node.
- If value is not null, let the declarations be the result of
parse a CSS declaration block from a string value.
To update style attribute for declaration block means to run the steps below:
- Assert: declaration block's readonly flag is unset.
- Let owner node be declaration block's owner node.
- If owner node is null, then return.
- Set declaration block's updating flag.
- Set an attribute value for owner node using "
style" and the result of
serializing declaration block.
- Unset declaration block's updating flag.
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.
[Exposed=Window]
interface CSSStyleDeclaration {
[CEReactions] attribute CSSOMString cssText;
readonly attribute unsigned long length;
getter CSSOMString item(unsigned long index);
CSSOMString getPropertyValue(CSSOMString property);
CSSOMString getPropertyPriority(CSSOMString property);
[CEReactions] void setProperty(CSSOMString property, [TreatNullAs=EmptyString] CSSOMString value, [TreatNullAs=EmptyString] optional CSSOMString priority = "");
[CEReactions] void setPropertyValue(CSSOMString property, [TreatNullAs=EmptyString] CSSOMString value);
[CEReactions] void setPropertyPriority(CSSOMString property, [TreatNullAs=EmptyString] CSSOMString priority);
[CEReactions] CSSOMString removeProperty(CSSOMString property);
readonly attribute CSSRule? parentRule;
[CEReactions] attribute [TreatNullAs=EmptyString] CSSOMString 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 attribute must return the result of
serializing the declarations.
Setting the {{CSSStyleDeclaration/cssText}} attribute must run these steps:
- If the readonly flag is set,
then throw a {{NoModificationAllowedError}} exception.
- Empty the declarations.
- 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.
- Update style attribute for the CSS declaration block.
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:
- Let property be property converted to ASCII lowercase.
- If property is a shorthand property, then follow these substeps:
- Let list be a new empty array.
- For each longhand property longhand that property maps to, in canonical order, follow these substeps:
- 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.
- If declaration is null, then return the empty string.
- Append the declaration to list.
- If important flags of all declarations in list are same,
then return the serialization of list.
- Return the empty string.
- If property is a case-sensitive
match for a property name of a CSS declaration in the
declarations, then return the result of invoking
serialize a CSS value of that declaration.
- Return the empty string.
The getPropertyPriority(property) method must run these steps:
- If property is not a custom property, follow these substeps:
- Let property be property converted to ASCII lowercase.
- 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 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".
- Return the empty string.
E.g. for background-color:lime !IMPORTANT the return
value would be "important".
The setProperty(property, value, priority) method must run these steps:
- If the readonly flag is set,
then throw a {{NoModificationAllowedError}} exception.
- If property is not a custom property, follow these substeps:
- Let property be property converted to ASCII lowercase.
- If property is not a case-sensitive match for a supported CSS property, then return.
- 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 parsing value for property property.
Note: value can not include "
!important".
- If component value list is null, then return.
- 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.
- 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.
- Update style attribute for the CSS declaration block.
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, follow these steps:
- If property is a case-sensitive match for a property
name of a CSS declaration in declarations, let declaration be that CSS declaration.
- Otherwise, append a new CSS declaration with the property name property
to declarations and let declaration be that CSS declaration.
- Set declaration's value to component value list.
- If the important flag is set, set declaration's important flag.
Otherwise, unset declaration's important flag.
The setPropertyValue(property, value) method must run these
steps:
- If the readonly flag is set,
then throw a {{NoModificationAllowedError}} exception.
- If property is not a custom property, follow these substeps:
- Let property be property converted to ASCII lowercase.
- If property is not a case-sensitive match for a supported CSS property, then return.
- If value is the empty string, invoke {{CSSStyleDeclaration/removeProperty()}}
with property as argument and return.
-
Let component value list be the result of parsing value for property property.
Note: value can not include "
!important".
- If component value list is null, then return.
- 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.
- Otherwise, set the CSS declaration value property to the value component value
list, and with the list of declarations being the declarations.
- Update style attribute for the CSS declaration block.
To set a CSS declaration value to a value component value list in a list of declarations declarations, follow these steps:
- If property is a case-sensitive match for a property
name of a CSS declaration in declarations, let declaration be that CSS declaration.
- Otherwise, append a new CSS declaration with the property name property
to declarations and let declaration be that CSS declaration.
- Set declaration's value to component value list.
The setPropertyPriority(property, priority) method must run
these steps:
- If the readonly flag is set,
then throw a {{NoModificationAllowedError}} exception.
- If property is not a custom property, follow these substeps:
- Let property be property converted to ASCII lowercase.
- If property is not a case-sensitive match for a supported CSS property, then return.
- If priority is not the empty string and is not an ASCII case-insensitive match for the string
"
important", then return.
- 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.
- 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.
- Update style attribute for the CSS declaration block.
To set a CSS declaration priority property optionally with an important flag set, in a list of declarations
declarations, follow these steps:
- If property is a case-sensitive match for a property
name of a CSS declaration in declarations, let declaration be that CSS declaration.
- Otherwise, return.
- If the important flag is set, set declaration's important flag. Otherwise,
unset declaration's important flag.
The removeProperty(property) method must run these steps:
- If the readonly flag is set,
then throw a {{NoModificationAllowedError}} exception.
- If property is not a custom property,
let property be property converted to ASCII lowercase.
- Let value be the return value of invoking {{CSSStyleDeclaration/getPropertyValue()}}
with property as argument.
- Let removed be false.
- If property is a shorthand property, for each longhand property longhand that property maps to:
- If longhand is not a property name of a CSS declaration
in the declarations, continue.
- Remove that CSS declaration and let removed be true.
- Otherwise, if property is a case-sensitive match for a
property name of a CSS declaration in the
declarations, remove that CSS declaration and let removed be true.
- If removed is true, Update style attribute for the CSS declaration block.
- Return value.
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 c
converted 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 c
converted 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:
- Let list be the value returned by invoking parse a list of component values from value.
- 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:
- If this algorithm is invoked with a list list, follow these substeps:
- 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.
- If shorthand cannot represent the values of list in its grammar, then return the empty string.
- Let trimmed list be a new empty array.
- 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.
- If trimmed list is empty, append the value of the first item in list to trimmed list.
- Let values be a new empty array.
- For each CSS declaration declaration in trimmed list, invoke serialize a CSS value of
declaration, and append the result to values.
- Return the result of joining values as appropriate according to the grammar of shorthand.
- Let values be a new empty array.
- Append the result of invoking serialize a CSS component value of declaration's
value to values.
- 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.
- 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
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:
- If the alpha component of the color is equal to one, then return the serialization of the
rgb() functional equivalent of the opaque color.
- 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:
- The string "
rgb(".
- The shortest base-ten integer serialization of the color's red component.
- The string "
, ".
- The shortest base-ten serialization of the color's green component.
- The string "
, ".
- The shortest base-ten serialization of the color's blue component.
- The string "
)".
The serialization of the rgba() functional equivalent is the concatenation of the following:
- The string "
rgba(".
- The shortest base-ten serialization of the color's red component.
- The string "
, ".
- The shortest base-ten serialization of the color's green component.
- The string "
, ".
- The shortest base-ten serialization of the color's blue component.
- The string "
, ".
- The serialization of the color's alpha component as an <alphavalue>.
- 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:
- If the color was explicitly specified by the author, then return the original, author specified color value.
- Otherwise, return the value that would be returned if the color were a component of a computed value.
Issue: 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:
- Let alpha be the given integer.
- 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.
- 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.
- 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:
- 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".
- Let each item in list be the result of invoking serialize a CSS component value on that item.
- Append the result of invoking serialize a comma-separated list on list to s.
- Append "
)" (U+0029) to s.
- Return s.
- <frequency>
- The frequency in hertz serialized as per <number> followed by
the literal string "
hz".
- <identifier>
- The identifier
serialized as an identifier.
- <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".
Issue: 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 CSS pixel serialized as per
<number> followed by the literal string "
dppx".
- <shape>
-
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>.
- Let each item in list be the result of invoking serialize a CSS component value of that item.
- Append the result of invoking serialize a comma-separated list on list to s.
- Append "
)" (U+0029) to s.
- Return s.
- <string>
- <family-name>
- <specific-voice>
- The string
serialized as a string.
- <time>
- The time in seconds serialized as per <number> followed by
the literal string "
s".
- <uri>
- The absolute-URL string
serialized as URL.
<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 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.
| 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}} Interface {#the-elementcssinlinestyle-interface}
------------------------------------------------------------------------------
The ElementCSSInlineStyle interface provides access to inline style properties of an element.
[Exposed=Window,
NoInterfaceObject]
interface ElementCSSInlineStyle {
[SameObject, PutForwards=cssText] readonly attribute CSSStyleDeclaration style;
};
The style attribute must return a CSS declaration block object whose
readonly flag is unset, whose parent CSS rule is null, and
whose owner node is 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: [[SVG11]]
SVGElement implements ElementCSSInlineStyle;
Extensions to the {{Window}} Interface {#extensions-to-the-window-interface}
----------------------------------------------------------------------------
partial interface Window {
[NewObject] CSSStyleDeclaration getComputedStyle(Element elt, optional CSSOMString? pseudoElt);
};
The getComputedStyle(elt, pseudoElt) method must run these
steps:
- Let doc be the
{{Document}}
associated with the
Window object on
which the method was invoked.
- Let obj be elt.
- If pseudoElt is as an
ASCII case-insensitive match for
either ":before" or "::before" let
obj be the ''::before'' pseudo-element of
elt.
- If pseudoElt is as an
ASCII case-insensitive match for
either ":after" or "::after" let
obj be the ''::after'' pseudo-element of
elt.
-
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
{{Window/getComputedStyle()}} was invoked to compute the CSS declaration block.
- parent CSS rule
- Null.
- owner node
- obj.
The {{Window/getComputedStyle()}} method exposes information from CSS style
sheets with the origin-clean flag unset.
Utility APIs {#utility-apis}
============================
The CSS.escape() Method {#the-css.escape()-method}
------------------------------------------------------
The CSS interface holds useful CSS-related functions that do not belong elsewhere.
[Exposed=Window]
interface CSS {
static CSSOMString escape(CSSOMString ident);
};
The escape(ident) method 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 static functions on the {{CSS}} interface 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'
- 'line-height'
- 'outline-color'
- A resolved value special case property like 'color' defined in another specification
- The resolved value is the used value.
- 'block-size'
- 'height'
- 'inline-size'
- 'margin-block-end'
- 'margin-block-start'
- 'margin-bottom'
- 'margin-inline-end'
- 'margin-inline-start'
- 'margin-left'
- 'margin-right'
- 'margin-top'
- 'padding-block-end'
- 'padding-block-start'
- 'padding-bottom'
- 'padding-inline-end'
- 'padding-inline-start'
- 'padding-left'
- 'padding-right'
- 'padding-top'
- 'width'
- A resolved value special case property like 'height' defined in another specification
- If the property applies to the element or pseudo-element and the resolved value of the
'display' property is not ''display/none'' or ''display/contents'', then the resolved value
is the used value. Otherwise the resolved value is the computed value.
- 'bottom'
- 'left'
- 'inset-block-end'
- 'inset-block-start'
- 'inset-inline-end'
- 'inset-inline-start'
- 'right'
- 'top'
- 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
- As defined in the relevant specification.
- Any other property
- The resolved value is the computed value.
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 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.
- {{CSSStyleDeclaration/setPropertyValue()}} and
{{CSSStyleDeclaration/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.
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.