HTML

Living Standard — Last Updated 24 September 2023

    1. 2.6 Common DOM interfaces
      1. 2.6.1 Reflecting content attributes in IDL attributes
      2. 2.6.2 Using reflect in specifications
      3. 2.6.3 Collections
        1. 2.6.3.1 The HTMLAllCollection interface
          1. 2.6.3.1.1 [[Call]] ( thisArgument, argumentsList )
        2. 2.6.3.2 The HTMLFormControlsCollection interface
        3. 2.6.3.3 The HTMLOptionsCollection interface
      4. 2.6.4 The DOMStringList interface

2.6 Common DOM interfaces

2.6.1 Reflecting content attributes in IDL attributes

The building blocks for reflecting are as follows:

A reflected IDL attribute can be defined to reflect a reflected content attribute name of a reflected target. In general this means that the IDL attribute getter returns the current value of the content attribute, and the setter changes the value of the content attribute to the given value.

If the reflected target is an element, then the reflected IDL attribute can additionally declare to support ElementInternals. This means that the ElementInternals interface also has a reflected IDL attribute, with the same identifier, and that reflected IDL attribute reflects the same reflected content attribute name.

The fooBar IDL attribute must reflect the foobar content attribute and support ElementInternals.

Reflected targets have these associated algorithms:

For a reflected target that is an element element, these are defined as follows:

get the element
  1. Return element.

get the content attribute
  1. Let attribute be the result of running get an attribute by namespace and local name given null, the reflected content attribute name, and element.

  2. If attribute is null, then return null.

  3. Return attribute's value.

set the content attribute with a string value
  1. Set an attribute value given element, the reflected content attribute name, and value.

delete the content attribute
  1. Remove an attribute by namespace and local name given null, the reflected content attribute name, and element.

For a reflected target that is an ElementInternals object elementInternals, they are defined as follows:

get the element
  1. Return elementInternals's target element.

get the content attribute
  1. If elementInternals's target element's internal content attribute map[the reflected content attribute name] does not exist, then return null.

  2. Return elementInternals's target element's internal content attribute map[the reflected content attribute name].

set the content attribute with a string value
  1. Set elementInternals's target element's internal content attribute map[the reflected content attribute name] to value.

delete the content attribute
  1. Remove elementInternals's target element's internal content attribute map[the reflected content attribute name].

This results in somewhat redundant data structures for ElementInternals objects as their target element's internal content attribute map cannot be directly manipulated and as such reflection is only happening in a single direction. This approach was nevertheless chosen to make it less error-prone to define IDL attributes that are shared between reflected targets and benefit from common API semantics.


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 reflected IDL attribute has the type

  • The getter steps are:

    1. Let element be the result of running this's get the element.

    2. Let contentAttributeValue be the result of running this's get the content attribute.

    3. Let attributeDefinition be the attribute definition of element's content attribute whose namespace is null and local name is the reflected content attribute name.

    4. If attributeDefinition indicates it is an enumerated attribute and the reflected IDL attribute is defined to be limited to only known values:

      1. If contentAttributeValue does not correspond to any state of attributeDefinition (e.g., it is null and there is no missing value default), or that it is in a state of attributeDefinition with no associated keyword value, then return the empty string.

      2. Return the canonical keyword for the state of attributeDefinition that contentAttributeValue corresponds to.

    5. If contentAttributeValue is null, then return the empty string.

    6. Return contentAttributeValue.

  • The setter steps are to run this's set the content attribute with the given value.

    If a reflected IDL attribute has the type DOMString?:

    If a reflected IDL attribute has the type

  • The getter steps are:

    1. Let element be the result of running this's get the element.

    2. Let contentAttributeValue be the result of running this's get the content attribute.

    3. Let attributeDefinition be the attribute definition of element's content attribute whose namespace is null and local name is the reflected content attribute name.

    4. If attributeDefinition indicates it contains a URL:

      1. If contentAttributeValue is null, then return the empty string.

      2. Let urlString be the result of encoding-parsing-and-serializing a URL given contentAttributeValue, relative to element's node document.

      3. If urlString is not failure, then return urlString.

    5. Return contentAttributeValue, converted to a scalar value string.

  • The setter steps are to run this's set the content attribute with the given value.

    If a reflected IDL attribute has the type

  • The getter steps are:

    1. Let contentAttributeValue be the result of running this's get the content attribute.

    2. If contentAttributeValue is null, then return false.

    3. Return true.

  • The setter steps are:

    1. If the given value is false, then run this's delete the content attribute.

    2. If the given value is true, then run this's set the content attribute with the empty string.

    This corresponds to the rules for boolean content attributes.

    If a reflected IDL attribute has the type limited to only non-negative numbers and optionally with a default value defaultValue:

    If a reflected IDL attribute has the type , optionally limited to only positive numbers, limited to only positive numbers with fallback, or clamped to the range [clampedMin, clampedMax], and optionally with a default value defaultValue:

    If a reflected IDL attribute has the type limited to only positive numbers and optionally with a default value defaultValue:

    The values Infinity and Not-a-Number (NaN) values throw an exception on setting, as defined in Web IDL. [WEBIDL]

    If a reflected IDL attribute has the type this and associated attribute's local name is the reflected content attribute name. Specification authors cannot use support ElementInternals for IDL attributes of this type.

    If a reflected IDL attribute has the type T?, where T is either

  • Let attr be the reflected content attribute name.

  • Its reflected target has an explicitly set attr-element, which is a weak reference to an element or null. It is initially null.

  • Its reflected target has an attr-associated element. To compute the attr-associated element for such a reflected target reflectedTarget:

    1. Let element be the result of running reflectedTarget's get the element.

    2. Let contentAttributeValue be the result of running reflectedTarget's get the content attribute.

    3. If reflectedTarget's explicitly set attr-element is not null:

    4. Otherwise, if contentAttributeValue is not null, return the first element candidate, in tree order, that meets the following criteria:

      • candidate's root is the same as element's root,
      • candidate's ID is contentAttributeValue, and
      • candidate implements T.

      If no such element exists, then return null.

    5. Return null.

  • The getter steps are to return this's attr-associated element.

  • The setter steps are:

    1. If the given value is null, then:

      1. Set this's explicitly set attr-element to null.

      2. Run this's delete the content attribute.

      3. Return.

    2. Run this's set the content attribute with the empty string.

    3. Set this's explicitly set attr-element to a weak reference to the given value.

  • For element reflected targets only: the following attribute change steps, given element, localName, oldValue, value, and namespace, are used to synchronize between the content attribute and the IDL attribute:

    1. If localName is not attr or namespace is not null, then return.

    2. Set element's explicitly set attr-element to null.

    Reflected IDL attributes of this type are strongly encouraged to have their identifier end in "Element" for consistency.

    If a reflected IDL attribute has the type FrozenArray<T>?, where T is either

    Reflected IDL attributes of this type are strongly encouraged to have their identifier end in "Elements" for consistency.

    2.6.2 Using reflect in specifications

    Reflection is primarily about improving web developer ergonomics by giving them typed access to content attributes through reflected IDL attributes. The ultimate source of truth, which the web platform builds upon, is the content attributes themselves. That is, specification authors must not use the reflected IDL attribute getter or setter steps, but instead must use the content attribute presence and value. (Or an abstraction on top, such as the state of an enumerated attribute.)

    Two important exceptions to this are reflected IDL attributes whose type is one of the following: