Living Standard — Last Updated 28 January 2023
Some IDL attributes are defined to reflect a particular content attribute. This means that on getting, the IDL attribute returns the current value of the content attribute, and on setting, the IDL attribute changes the value of the content attribute to the given value.
In general, on getting, if the content attribute is not present, the IDL attribute must act as if the content attribute's value is the empty string; and on setting, if the content attribute is not present, it must first be added.
IDL attributes of type DOMString?
that reflect enumerated content attributes can be limited to only known values.
Per the processing models below, those will cause the getters for such IDL attributes to only
return keywords for those enumerated attributes, or the empty string or null.
If a reflecting IDL attribute has the type The getter steps are: If the content attribute is an enumerated attribute, and the IDL attribute is
limited to only known values: If the content attribute is not in any state (e.g. the attribute is missing and there
is no missing value default), or the content attribute
is in a state with no associated keyword value, then return the empty string. Return the canonical keyword for the state of the content
attribute. Otherwise: Return the content attribute's value. The setter steps are to set the content attribute's value to the given value.
If a reflecting IDL attribute has the type The getter steps are: Assert: the content attribute is an enumerated
attribute. Assert: the IDL attribute is limited to only known
values. Assert: the content attribute is in some state. If the content attribute is in a state with no associated keyword value, then return
null. Return the canonical keyword for the state of the content
attribute. The setter steps are: If the given value is null, then remove the content attribute. Otherwise, set the content attribute's value to the given value. If a reflecting IDL attribute has the type The getter steps are: If the content attribute is defined to contain a URL: If the content attribute is absent, then return the empty string. Parse the value of the content attribute relative
to the element's node document. If that is successful, then return the resulting URL string. Otherwise, return the value of the content attribute, converted to a Otherwise: Return the value of the content attribute, converted to a The setter steps are to set the content attribute's value to the given value.
If a reflecting IDL attribute is a If a reflecting IDL attribute has a signed integer type ( If a reflecting IDL attribute has a signed integer type ( If a reflecting IDL attribute has an unsigned integer type ( If a reflecting IDL attribute has an unsigned integer type ( If a reflecting IDL attribute has an unsigned integer type ( If a reflecting IDL attribute has an unsigned integer type ( If a reflecting IDL attribute has a floating-point number type ( If a reflecting IDL attribute has a floating-point number type ( The values Infinity and Not-a-Number (NaN) values throw an exception on setting,
as defined in Web IDL. [WEBIDL] If a reflecting IDL attribute has the type If a reflecting IDL attribute attr has the type Elements of the type this IDL attribute appears on have an explicitly set
attr-element, which is a weak reference to an element or null. It is initially
null. Elements of the type this IDL attribute appears on have an attr-associated element. To compute the attr-associated
element for such an element element: If element's explicitly set attr-element is not null: If element's explicitly set attr-element is a
descendant of any of element's shadow-including ancestors, then return
element's explicitly set attr-element. Otherwise, return null. Otherwise, if the content attribute is present on element, then return the first
element candidate, in tree order, that meets the following
criteria: If no such element exists, then return null. Return null. Other parts of this specification, or other specifications using attribute
reflection, are expected to consult an element's attr-associated
element. An element's explicitly set attr-element is an internal
implementation detail of its attr-associated element and is not to be
used directly. The getter steps are to return this's attr-associated
element. The setter steps are: If the given value is null, then: Set this's explicitly set attr-element to
null. Remove the content attribute from this. Return. Set the content attribute's value for this to the empty string. Set this's explicitly set attr-element to a weak
reference to the given value. The following attribute change
steps, given element, localName, oldValue,
value, and namespace, are used to synchronize between the content
attribute and the IDL attribute: If localName is not the content attribute's local name, or
namespace is not null, then return. Set element's explicitly set attr-element to
null. If a reflecting IDL attribute attr has the type Elements of the type this IDL attribute appears on have explicitly set
attr-elements, which is either a list of weak references to elements
or null. It is initially null. Elements of the type this IDL attribute appears on have cached
attr-associated elements, which is a Elements of the type this IDL attribute appears on have attr-associated elements. To compute the attr-associated
elements for such an element element: Let elements be an empty list. If element's explicitly set attr-elements is not
null, then: For each attrElement in the element's
explicitly set attr-elements: If attrElement is not a descendant of any of element's shadow-including ancestors, then
continue. Append attrElement to elements. Otherwise: If the content attribute is not present on element, return null. Let tokens be the content attribute's value, split on ASCII whitespace.
For each id in tokens: Let candidate be the first element, in tree order, that meets the
following criteria: If no such element exists, then continue. Append candidate to
elements. Return elements. Other parts of this specification, or other specifications using attribute
reflection, are expected to consult an element's attr-associated
elements. An element's explicitly set attr-elements is an internal
implementation detail of its attr-associated elements and is not to be
used directly. Similarly, the element's cached attr-associated elements
is an internal implementation detail of the IDL attribute's getter. The getter steps are: Let elements be this's attr-associated
elements. If the contents of elements is equal to the contents of this's
cached attr-associated elements, then return this's
cached attr-associated elements. Let elementsAsFrozenArray be elements, converted to a Set this's cached attr-associated elements to
elementsAsFrozenArray. Return elementsAsFrozenArray. This extra caching layer is necessary to preserve the invariant that The setter steps are: If the given value is null: Set this's explicitly set attr-elements to
null. Remove the content attribute from this. Return. Set the content attribute's value for this to the empty string. Let elements be an empty list. For each element in the given value: Append a weak reference to element to
elements. Set this's explicitly set attr-elements to
elements. The following attribute change
steps, given element, localName, oldValue,
value, and namespace, are used to synchronize between the content
attribute and the IDL attribute: If localName is not the content attribute's local name, or
namespace is not null, then return. Set element's explicitly set attr-elements to
null. The The All Objects that implement the Objects that implement the The ToBoolean abstract operation in JavaScript returns
false when given objects implementing the The IsLooselyEqual abstract operation,
when given objects implementing the The These special behaviors are motivated by a desire for compatibility with two classes of legacy
content: one that uses the presence of The object's supported property indices are as defined for
The supported property names consist of the non-empty values of all the The The indexed property getter must return the result of getting the "all"-indexed element from this
given the passed index. The The If nameOrIndex was not provided, return null. Return the result of getting the
"all"-indexed or named element(s) from this, given
nameOrIndex. The following elements are "all"-named elements:
To get the "all"-indexed element from an
To get the "all"-named element(s) from an
If name is the empty string, return null. Let subCollection be an "all"-named elements with a elements with an ID equal to name. If there is exactly one element in subCollection, then return that
element. Otherwise, if subCollection is empty, return null. Otherwise, return subCollection. To get the "all"-indexed or named
element(s) from an If nameOrIndex, converted to a
JavaScript String value, is an array index property name, return the result of getting the "all"-indexed element from
collection given the number represented by nameOrIndex. Return the result of getting the "all"-named
element(s) from collection given nameOrIndex. If argumentsList's size is zero, or if
argumentsList[0] is undefined, return null. Let nameOrIndex be the result of converting argumentsList[0] to a Return the result of converting
result to an ECMAScript value. The thisArgument is ignored, and thus code such as The Support in all current engines. Support in all current engines. Returns the number of elements in collection. Returns the item at index index in collection. The items are sorted
in tree order. HTMLFormControlsCollection/namedItem Support in all current engines. Returns the item with ID or If there are multiple matching items, then a Returns the value of the first checked radio button represented by
radioNodeList. Checks the first first radio button represented by radioNodeList that has value
value. The object's supported property indices are as defined for
The supported property names consist of the non-empty values of all the The Members of the Support in all current engines. The Let element be the first element in tree order
represented by the If element is null, return the empty string. If element is an element with no Otherwise, return the value of element's On setting, the If the new value is the string " Otherwise: let element be the first element in tree order
represented by the If element is not null, then set its checkedness to true. Support in all current engines. The Returns the number of elements in collection. When set to a smaller number than the existing length, truncates the number of
When set to a greater number than the existing length, if that number is less than or equal
to 100000, adds new blank Returns the item at index index in collection. The items are sorted
in tree order. When index is a greater number than the number of items in collection,
adds new blank When set to null, removes the item at index index from collection. When set to an Returns the item with ID or If there are multiple matching items, then the first is returned. Inserts element before the node given by before. The before argument can be a number, in which case element is inserted
before the item with that number, or an element from collection, in which case
element is inserted before that element. If before is omitted, null, or a number out of range, then element will
be added at the end of the list. Throws a " Removes the item with index index from collection. Returns the index of the first selected item, if any, or −1 if there is no selected
item. Changes the selection to the The object's supported property indices are as defined for
The The Let current be the number of nodes represented by the
collection. If the given value is greater than current, then: If the given value is less than current, then: Let n be current − value. Remove the last n nodes in the collection from their parent nodes. Setting The supported property names consist of the non-empty values of all the When the user agent is to set the value of a new
indexed property or set the value of an existing indexed property for a given
property index index to a new value value, it must run the following
algorithm: If value is null, invoke the steps for the Let length be the number of nodes represented by the
collection. Let n be index minus length. If n is greater than zero, then append a If n is greater than or equal to zero, append value to the The If element is an ancestor of the If before is a node, then let reference be that
node. Otherwise, if before is an integer, and there is a beforeth node in the collection, let reference be that node.
Otherwise, let reference be null. If reference is not null, let parent be the parent
node of reference. Otherwise, let parent be the
Pre-insert element into parent node before
reference. The If the number of nodes represented by the collection is zero, return. If index is not a number greater than or equal to 0 and less than the
number of nodes represented by the collection, return. Let element be the indexth element in the
collection. Remove element from its parent node. The Support in all current engines. The New APIs must use Returns the number of strings in strings. Returns the string with index index from strings. Returns true if strings contains string, and false
otherwise. Each The The The The DOMString?
:
boolean content attributes.)
rules for parsing signed integers, and if that is successful, and the
value is in the range of the IDL attribute's type, the resulting value must be returned. If, on
the other hand, it fails or returns an out of range value, or if the attribute is absent, then the
default value must be returned instead, or 0 if there is no default value. On setting, the given
value must be converted to the shortest possible string representing the number as a valid
integer and then that string must be used as the new content attribute value.
limited to only non-negative numbers then, on getting, the content attribute
must be parsed according to the rules for parsing non-negative integers, and if that
is successful, and the value is in the range of the IDL attribute's type, the resulting value must
be returned. If, on the other hand, it fails or returns an out of range value, or if the attribute
is absent, the default value must be returned instead, or −1 if there is no default value.
On setting, if the value is negative, the user agent must throw an
"
IndexSizeError
" valid
non-negative integer and then that string must be used as the new content attribute
value.
) then, on getting, the content attribute must be
parsed according to the rules for parsing non-negative integers, and if that is
successful, and the value is in the range 0 to 2147483647 inclusive, the resulting value must be
returned. If, on the other hand, it fails or returns an out of range value, or if the attribute is
absent, the default value must be returned instead, or 0 if there is no default value. On setting,
first, if the new value is in the range 0 to 2147483647, then let n be the new value,
otherwise let n be the default value, or 0 if there is no default value; then,
n must be converted to the shortest possible string representing the number as a
valid non-negative integer and that string must be used as the new content attribute
value.
) that is limited to only non-negative numbers
greater than zero, then the behavior is similar to the previous case, but zero is not
allowed. On getting, the content attribute must first be parsed according to the rules for
parsing non-negative integers, and if that is successful, and the value is in the range 1
to 2147483647 inclusive, the resulting value must be returned. If, on the other hand, it fails or
returns an out of range value, or if the attribute is absent, the default value must be returned
instead, or 1 if there is no default value. On setting, if the value is zero, the user agent must
throw an "
IndexSizeError
" n be the new value,
otherwise let n be the default value, or 1 if there is no default value; then,
n must be converted to the shortest possible string representing the number as a
valid non-negative integer and that string must be used as the new content attribute
value.
) that is limited to only non-negative numbers
greater than zero with fallback, then the behavior is similar to the previous case, but
disallowed values are converted to the default value. On getting, the content attribute must first
be parsed according to the rules for parsing non-negative integers, and if that is
successful, and the value is in the range 1 to 2147483647 inclusive, the resulting value must be
returned. If, on the other hand, it fails or returns an out of range value, or if the attribute is
absent, the default value must be returned instead. On setting, first, if the new value is in the
range 1 to 2147483647, then let n be the new value, otherwise let n be the
default value; then, n must be converted to the shortest possible string representing
the number as a valid non-negative integer and that string must be used as the new
content attribute value.
) that is clamped to the range
[min, max], then on getting, the content attribute must first be parsed
according to the rules for parsing non-negative integers, and if that is successful,
and the value is between min and max inclusive, the resulting value must be
returned. If it fails, the default value must be returned. If it succeeds but the value is less
than min, min must be returned. If it succeeds but the value is greater than
max, max must be returned. On setting, it behaves the same as setting a
regular reflected unsigned integer.
), then, on getting, the content attribute must be parsed according to the
rules for parsing floating-point number values, and if that is successful, the
resulting value must be returned. If, on the other hand, it fails, or if the attribute is absent,
the default value must be returned instead, or 0.0 if there is no default value. On setting, the
given value must be converted to the best representation of the number as a floating-point
number and then that string must be used as the new content attribute value.
) that is limited to numbers greater than zero, then the behavior is
similar to the previous case, but zero and negative values are not allowed. On getting, the
content attribute must be parsed according to the rules for parsing floating-point number
values, and if that is successful and the value is greater than 0.0, the resulting value
must be returned. If, on the other hand, it fails or returns an out of range value, or if the
attribute is absent, the default value must be returned instead, or 0.0 if there is no default
value. On setting, if the value is less than or equal to zero, then the value must be ignored.
Otherwise, the given value must be converted to the best representation of the number as a
floating-point number and then that string must be used as the new content attribute
value.
T?
, where T is either FrozenArray<T>?
, where T is either
FrozenArray<T>?
. It is initially null.FrozenArray<T>?
.element.reflectedElements === element.reflectedElements
.2.6.2 Collections
HTMLFormControlsCollection
and HTMLOptionsCollection
interfaces
are collections derived from the
HTMLAllCollection
interface is a collection, but is not so derived.2.6.2.1 The
HTMLAllCollection
interfaceHTMLAllCollection
interface is used for the legacy document.all
attribute. It operates similarly to
HTMLAllCollection
objects are rooted at a Document
and have a filter that matches all elements, so the elements represented by the
collection of an HTMLAllCollection
object consist of all the descendant
elements of the root Document
.HTMLAllCollection
interface are legacy platform objects with an additional [[Call]] internal
method described in the section below. They also have an
[[IsHTMLDDA]] internal slot.HTMLAllCollection
interface have several unusual
behaviors, due of the fact that they have an [[IsHTMLDDA]] internal slot:HTMLAllCollection
interface.HTMLAllCollection
interface, returns true when
compared to the undefined
and null
values.
(Comparisons using the IsStrictlyEqual abstract
operation, and IsLooselyEqual comparisons to other values such as strings or objects, are
unaffected.)typeof
operator in JavaScript returns the string
"undefined"
when applied to objects implementing the
HTMLAllCollection
interface.document.all
as a
way to detect legacy user agents, and one that only supports those legacy user agents and uses
the document.all
object without testing for its presence
first. [JAVASCRIPT][
id
attributes of all the elements represented by the
collection, and the non-empty values of all the name
attributes of
all the "all"-named elements represented by the collection, in
tree order, ignoring later duplicates, with the id
of
an element preceding its name
if it contributes both, they differ from
each other, and neither is the duplicate of an earlier entry.length
getter steps are to return the number
of nodes represented by the collection.namedItem(name)
method steps are
to return the result of getting the "all"-named
element(s) from this given name.item(nameOrIndex)
method steps
are:
a
,
button
,
embed
,
form
,
frame
,
frameset
,
iframe
,
img
,
input
,
map
,
meta
,
object
,
select
, and
textarea
HTMLAllCollection
collection given an index index, return the
indexth element in collection, or null if there is no such
indexth element.HTMLAllCollection
collection given a name name, perform the
following steps:Document
as collection, whose filter matches only elements that are
either:name
attribute equal to
name, or,HTMLAllCollection
collection given
nameOrIndex:
2.6.2.1.1 [[Call]] ( thisArgument, argumentsList )
result be the result of getting the "all"-indexed or named element(s)
from this
HTMLAllCollection
given nameOrIndex.Function.prototype.call.call(document.all, null, "x")
will still search for
elements. (document.all.call
does not exist, since document.all
does not inherit from Function.prototype
.)2.6.2.2 The
HTMLFormControlsCollection
interfaceHTMLFormControlsCollection
interface is used for
collections of listed
elements in form
elements.
Opera12.1+Edge79+
Edge (Legacy)12+Internet ExplorerNo
Firefox Android?Safari iOS1+Chrome Android?WebView Android?Samsung Internet?Opera Android12.1+
Opera?Edge79+
Edge (Legacy)12+Internet Explorer9+
Firefox Android?Safari iOS?Chrome Android?WebView Android?Samsung Internet?Opera Android?[
collection.length
element = collection.item(index)
element = collection[index]
element = collection.namedItem(name)
Opera12.1+Edge79+
Edge (Legacy)12+Internet ExplorerNo
Firefox Android?Safari iOS1+Chrome Android?WebView Android?Samsung Internet?Opera Android12.1+radioNodeList = collection.namedItem(name)
element = collection[name]
radioNodeList = collection[name]
name
name from collection.RadioNodeList
object containing all
those elements is returned.radioNodeList.value
radioNodeList.value = value
id
and name
attributes of all the
elements represented by the collection, in tree order, ignoring later
duplicates, with the id
of an element preceding its name
if it contributes both, they differ from each other, and neither is the
duplicate of an earlier entry.namedItem(name)
method
must act according to the following algorithm:id
attribute or a name
attribute equal to name, then return that node and stop the algorithm.id
attribute or a name
attribute equal
to name, then return null and stop the algorithm.RadioNodeList
object representing a live
view of the HTMLFormControlsCollection
object, further filtered so that the only
nodes in the RadioNodeList
object are those that have either an id
attribute or a name
attribute equal
to name. The nodes in the RadioNodeList
object must be sorted in
tree order.RadioNodeList
object.
RadioNodeList
interface inherited from the
Opera?Edge79+
Edge (Legacy)12+Internet Explorer9+
Firefox Android?Safari iOS?Chrome Android?WebView Android?Samsung Internet?Opera Android?value
IDL attribute on the
RadioNodeList
object, on getting, must return the value returned by running the
following steps:RadioNodeList
object that is an input
element whose
type
attribute is in the Radio Button state and whose checkedness is true. Otherwise, let it be null.value
attribute, return the string "on
".value
attribute.value
IDL attribute must run the
following steps:on
": let element be the first element in tree order
represented by the RadioNodeList
object that is an input
element whose
type
attribute is in the Radio Button state and whose value
content attribute is either absent, or present and equal to the new value, if any. If no such element exists, then instead let element be null.RadioNodeList
object that is an input
element whose
type
attribute is in the Radio Button state and whose value
content attribute is present and equal to the new value, if
any. If no such element exists, then instead let element be null.2.6.2.3 The
HTMLOptionsCollection
interface
Opera12.1+Edge79+
Edge (Legacy)12+Internet Explorer6+
Firefox Android?Safari iOS1+Chrome Android?WebView Android37+Samsung Internet?Opera Android12.1+HTMLOptionsCollection
interface is used for collections of option
elements. It is always
rooted on a select
element and has attributes and methods that manipulate that
element's descendants.[
collection.length
collection.length = value
option
elements in the container corresponding to collection.option
elements to the container corresponding to
collection.element = collection.item(index)
element = collection[index]
collection[index] = element
option
elements in the corresponding container.option
element, adds or replaces it at index index in
collection.element = collection.namedItem(name)
element = collection[name]
name
name from collection.collection.add(element[, before])
HierarchyRequestError
" element is an ancestor of the element into which it is to be inserted.
collection.remove(index)
collection.selectedIndex
collection.selectedIndex = index
option
element at index index in
collection.
length
getter steps are to return the
number of nodes represented by the collection.length
setter steps are:length
never removes
or adds any optgroup
elements, and never adds new children to existing
optgroup
elements (though it can remove children from them).id
and name
attributes of all the
elements represented by the collection, in tree order, ignoring later
duplicates, with the id
of an element preceding its name
if it contributes both, they differ from each other, and neither is
the duplicate of an earlier entry.remove
method with index as
the argument, and return.n-1 new
option
elements with no attributes and
no child nodes to the select
element on which the HTMLOptionsCollection
is rooted.select
element. Otherwise, replace the indexth element in the collection by value.add(element, before)
method must act according to the following algorithm:select
element on which
the HTMLOptionsCollection
is rooted, then throw a
"HierarchyRequestError
" before is an element, but that element isn't a descendant of the
select
element on which the HTMLOptionsCollection
is rooted, then throw
a "NotFoundError
" element and before are the same element, then
return.
select
element on which the HTMLOptionsCollection
is rooted.remove(index)
method must act
according to the following algorithm:selectedIndex
IDL attribute must act
like the identically named attribute on the select
element on which the
HTMLOptionsCollection
is rooted2.6.3 The
DOMStringList
interface
Opera12.1+Edge79+
Edge (Legacy)12+Internet Explorer10+
Firefox Android?Safari iOS?Chrome Android?WebView Android3+Samsung Internet?Opera Android12.1+DOMStringList
interface is a non-fashionable retro way of representing a list
of strings.[
sequence<DOMString>
or
equivalent rather than DOMStringList
.strings.length
strings[index]
strings.item(index)
strings.contains(string)
DOMStringList
object has an associated list.DOMStringList
interface supports indexed properties. The
supported property indices are the indices of this's
associated list.length
getter steps are to return
this's associated list's size.item(index)
method steps are to
return the indexth item in this's associated list, or null if
index plus one is greater than this's associated list's size.contains(string)
method steps
are to return true if this's associated list contains string, and false otherwise.