DOM

1. Infrastructure

This specification depends on the Infra Standard. [INFRA]

Some of the terms used in this specification are defined in Encoding, Selectors, Web IDL, XML, and Namespaces in XML. [ENCODING] [SELECTORS4] [WEBIDL] [XML] [XML-NAMES]

When extensions are needed, the DOM Standard can be updated accordingly, or a new standard can be written that hooks into the provided extensibility hooks for applicable specifications.

1.1. Trees

A tree is a finite hierarchical tree structure. In tree order is preorder, depth-first traversal of a tree.

An object that participates in a tree has a parent, which is either null or an object, and has children, which is an ordered set of objects. An object A whose parent is object B is a child of B.

The root of an object is itself, if its parent is null, or else it is the root of its parent. The root of a tree is any object participating in that tree whose parent is null.

An object A is called a descendant of an object B, if either A is a child of B or A is a child of an object C that is a descendant of B.

An inclusive descendant is an object or one of its descendants.

An object A is called an ancestor of an object B if and only if B is a descendant of A.

An inclusive ancestor is an object or one of its ancestors.

An object A is called a sibling of an object B, if and only if B and A share the same non-null parent.

An inclusive sibling is an object or one of its siblings.

An object A is preceding an object B if A and B are in the same tree and A comes before B in tree order.

An object A is following an object B if A and B are in the same tree and A comes after B in tree order.

The first child of an object is its first child or null if it has no children.

The last child of an object is its last child or null if it has no children.

The previous sibling of an object is its first preceding sibling or null if it has no preceding sibling.

The next sibling of an object is its first following sibling or null if it has no following sibling.

The index of an object is its number of preceding siblings, or 0 if it has none.

1.2. Ordered sets

The ordered set parser takes a string input and then runs these steps:

1. Let inputTokens be the result of splitting input on ASCII whitespace.

2. Let tokens be a new ordered set.

3. For each token in inputTokens, append token to tokens.

4. Return tokens.

The ordered set serializer takes a set and returns the concatenation of set using U+0020 SPACE.

1.3. Selectors

To scope-match a selectors string selectors against a node, run these steps:

1. Let s be the result of parse a selector selectors. [SELECTORS4]

2. If s is failure, then throw a "SyntaxError" DOMException.

3. Return the result of match a selector against a tree with s and node’s root using scoping root node. [SELECTORS4].

Support for namespaces within selectors is not planned and will not be added.

1.4. Namespaces

To validate a qualifiedName, throw an "InvalidCharacterError" DOMException if qualifiedName does not match the QName production.

To validate and extract a namespace and qualifiedName, run these steps:

1. If namespace is the empty string, then set it to null.

2. Validate qualifiedName.

3. Let prefix be null.

4. Let localName be qualifiedName.

5. If qualifiedName contains a U+003A (:), then:

   1. Let splitResult be the result of running strictly split given qualifiedName and U+003A (:).

   2. Set prefix to splitResult[0].

   3. Set localName to splitResult[1].

6. If prefix is non-null and namespace is null, then throw a "NamespaceError" DOMException.

7. If prefix is "xml" and namespace is not the XML namespace, then throw a "NamespaceError" DOMException.

8. If either qualifiedName or prefix is "xmlns" and namespace is not the XMLNS namespace, then throw a "NamespaceError" DOMException.

9. If namespace is the XMLNS namespace and neither qualifiedName nor prefix is "xmlns", then throw a "NamespaceError" DOMException.

10. Return namespace, prefix, and localName.

2. Events

2.1. Introduction to "DOM Events"

Throughout the web platform events are dispatched to objects to signal an occurrence, such as network activity or user interaction. These objects implement the EventTarget interface and can therefore add event listeners to observe events by calling addEventListener():

obj.addEventListener("load", imgFetched)

function imgFetched(ev) {
  // great success
  …
}

Event listeners can be removed by utilizing the removeEventListener() method, passing the same arguments.

Alternatively, event listeners can be removed by passing an AbortSignal to addEventListener() and calling abort() on the controller owning the signal.

Events are objects too and implement the Event interface (or a derived interface). In the example above ev is the event. ev is passed as an argument to the event listener’s callback (typically a JavaScript Function as shown above). Event listeners key off the event’s type attribute value ("load" in the above example). The event’s target attribute value returns the object to which the event was dispatched (obj above).

Although events are typically dispatched by the user agent as the result of user interaction or the completion of some task, applications can dispatch events themselves by using what are commonly known as synthetic events:

// add an appropriate event listener
obj.addEventListener("cat", function(e) { process(e.detail) })

// create and dispatch the event
var event = new CustomEvent("cat", {"detail":{"hazcheeseburger":true}})
obj.dispatchEvent(event)

Apart from signaling, events are sometimes also used to let an application control what happens next in an operation. For instance as part of form submission an event whose type attribute value is "submit" is dispatched. If this event’s preventDefault() method is invoked, form submission will be terminated. Applications who wish to make use of this functionality through events dispatched by the application (synthetic events) can make use of the return value of the dispatchEvent() method:

if(obj.dispatchEvent(event)) {
  // event was not canceled, time for some magic
  …
}

When an event is dispatched to an object that participates in a tree (e.g., an element), it can reach event listeners on that object’s ancestors too. Effectively, all the object’s inclusive ancestor event listeners whose capture is true are invoked, in tree order. And then, if event’s bubbles is true, all the object’s inclusive ancestor event listeners whose capture is false are invoked, now in reverse tree order.

Let’s look at an example of how events work in a tree:

<!doctype html>
<html>
 <head>
  <title>Boring example</title>
 </head>
 <body>
  <p>Hello <span id=x>world</span>!</p>
  <script>
   function test(e) {
     debug(e.target, e.currentTarget, e.eventPhase)
   }
   document.addEventListener("hey", test, {capture: true})
   document.body.addEventListener("hey", test)
   var ev = new Event("hey", {bubbles:true})
   document.getElementById("x").dispatchEvent(ev)
  </script>
 </body>
</html>

The debug function will be invoked twice. Each time the event’s target attribute value will be the span element. The first time currentTarget attribute’s value will be the document, the second time the body element. eventPhase attribute’s value switches from CAPTURING_PHASE to BUBBLING_PHASE. If an event listener was registered for the span element, eventPhase attribute’s value would have been AT_TARGET.

2.2. Interface Event

[Exposed=*]
interface Event {
  constructor(DOMString type, optional EventInit eventInitDict = {});

  readonly attribute DOMString type;
  readonly attribute EventTarget? target;
  readonly attribute EventTarget? srcElement; // legacy
  readonly attribute EventTarget? currentTarget;
  sequence<EventTarget> composedPath();

  const unsigned short NONE = 0;
  const unsigned short CAPTURING_PHASE = 1;
  const unsigned short AT_TARGET = 2;
  const unsigned short BUBBLING_PHASE = 3;
  readonly attribute unsigned short eventPhase;

  undefined stopPropagation();
           attribute boolean cancelBubble; // legacy alias of .stopPropagation()
  undefined stopImmediatePropagation();

  readonly attribute boolean bubbles;
  readonly attribute boolean cancelable;
           attribute boolean returnValue;  // legacy
  undefined preventDefault();
  readonly attribute boolean defaultPrevented;
  readonly attribute boolean composed;

  [LegacyUnforgeable] readonly attribute boolean isTrusted;
  readonly attribute DOMHighResTimeStamp timeStamp;

  undefined initEvent(DOMString type, optional boolean bubbles = false, optional boolean cancelable = false); // legacy
};

dictionary EventInit {
  boolean bubbles = false;
  boolean cancelable = false;
  boolean composed = false;
};

An Event object is simply named an event. It allows for signaling that something has occurred, e.g., that an image has completed downloading.

A potential event target is null or an EventTarget object.

An event has an associated target (a potential event target). Unless stated otherwise it is null.

An event has an associated relatedTarget (a potential event target). Unless stated otherwise it is null.

Other specifications use relatedTarget to define a relatedTarget attribute. [UIEVENTS]

An event has an associated touch target list (a list of zero or more potential event targets). Unless stated otherwise it is the empty list.

The touch target list is for the exclusive use of defining the TouchEvent interface and related interfaces. [TOUCH-EVENTS]

An event has an associated path. A path is a list of structs. Each struct consists of an invocation target (an EventTarget object), an invocation-target-in-shadow-tree (a boolean), a shadow-adjusted target (a potential event target), a relatedTarget (a potential event target), a touch target list (a list of potential event targets), a root-of-closed-tree (a boolean), and a slot-in-closed-tree (a boolean). A path is initially the empty list.

event = new Event(type [, eventInitDict])

Returns a new event whose type attribute value is set to type. The eventInitDict argument allows for setting the bubbles and cancelable attributes via object members of the same name.

event . type

Returns the type of event, e.g. "click", "hashchange", or "submit".

event . target

Returns the object to which event is dispatched (its target).

event . currentTarget

Returns the object whose event listener’s callback is currently being invoked.

event . composedPath()

Returns the invocation target objects of event’s path (objects on which listeners will be invoked), except for any nodes in shadow trees of which the shadow root’s mode is "closed" that are not reachable from event’s currentTarget.

event . eventPhase

Returns the event’s phase, which is one of NONE, CAPTURING_PHASE, AT_TARGET, and BUBBLING_PHASE.

event . stopPropagation()

When dispatched in a tree, invoking this method prevents event from reaching any objects other than the current object.

event . stopImmediatePropagation()

Invoking this method prevents event from reaching any registered event listeners after the current one finishes running and, when dispatched in a tree, also prevents event from reaching any other objects.

event . bubbles

Returns true or false depending on how event was initialized. True if event goes through its target’s ancestors in reverse tree order; otherwise false.

event . cancelable

Returns true or false depending on how event was initialized. Its return value does not always carry meaning, but true can indicate that part of the operation during which event was dispatched, can be canceled by invoking the preventDefault() method.

event . preventDefault()

If invoked when the cancelable attribute value is true, and while executing a listener for the event with passive set to false, signals to the operation that caused event to be dispatched that it needs to be canceled.

event . defaultPrevented

Returns true if preventDefault() was invoked successfully to indicate cancelation; otherwise false.

event . composed

Returns true or false depending on how event was initialized. True if event invokes listeners past a ShadowRoot node that is the root of its target; otherwise false.

event . isTrusted

Returns true if event was dispatched by the user agent, and false otherwise.

event . timeStamp

Returns the event’s timestamp as the number of milliseconds measured relative to the occurrence.

The type attribute must return the value it was initialized to. When an event is created the attribute must be initialized to the empty string.

The target getter steps are to return this’s target.

The srcElement getter steps are to return this’s target.

The currentTarget attribute must return the value it was initialized to. When an event is created the attribute must be initialized to null.

The composedPath() method steps are:

1. Let composedPath be an empty list.

2. Let path be this’s path.

3. If path is empty, then return composedPath.

4. Let currentTarget be this’s currentTarget attribute value.

5. Append currentTarget to composedPath.

6. Let currentTargetIndex be 0.

7. Let currentTargetHiddenSubtreeLevel be 0.

8. Let index be path’s size − 1.

9. While index is greater than or equal to 0:

   1. If path[index]'s root-of-closed-tree is true, then increase currentTargetHiddenSubtreeLevel by 1.

   2. If path[index]'s invocation target is currentTarget, then set currentTargetIndex to index and break.

   3. If path[index]'s slot-in-closed-tree is true, then decrease currentTargetHiddenSubtreeLevel by 1.

   4. Decrease index by 1.

10. Let currentHiddenLevel and maxHiddenLevel be currentTargetHiddenSubtreeLevel.

11. Set index to currentTargetIndex − 1.

12. While index is greater than or equal to 0:

    1. If path[index]'s root-of-closed-tree is true, then increase currentHiddenLevel by 1.

    2. If currentHiddenLevel is less than or equal to maxHiddenLevel, then prepend path[index]'s invocation target to composedPath.

    3. If path[index]'s slot-in-closed-tree is true, then:

       1. Decrease currentHiddenLevel by 1.

       2. If currentHiddenLevel is less than maxHiddenLevel, then set maxHiddenLevel to currentHiddenLevel.

    4. Decrease index by 1.

13. Set currentHiddenLevel and maxHiddenLevel to currentTargetHiddenSubtreeLevel.

14. Set index to currentTargetIndex + 1.

15. While index is less than path’s size:

    1. If path[index]'s slot-in-closed-tree is true, then increase currentHiddenLevel by 1.

    2. If currentHiddenLevel is less than or equal to maxHiddenLevel, then append path[index]'s invocation target to composedPath.

    3. If path[index]'s root-of-closed-tree is true, then:

       1. Decrease currentHiddenLevel by 1.

       2. If currentHiddenLevel is less than maxHiddenLevel, then set maxHiddenLevel to currentHiddenLevel.

    4. Increase index by 1.

16. Return composedPath.

The eventPhase attribute must return the value it was initialized to, which must be one of the following:

NONE (numeric value 0)

Events not currently dispatched are in this phase.

CAPTURING_PHASE (numeric value 1)

When an event is dispatched to an object that participates in a tree it will be in this phase before it reaches its target.

AT_TARGET (numeric value 2)

When an event is dispatched it will be in this phase on its target.

BUBBLING_PHASE (numeric value 3)

When an event is dispatched to an object that participates in a tree it will be in this phase after it reaches its target.

Initially the attribute must be initialized to NONE.

Each event has the following associated flags that are all initially unset:

• stop propagation flag
• stop immediate propagation flag
• canceled flag
• in passive listener flag
• composed flag
• initialized flag
• dispatch flag

The stopPropagation() method steps are to set this’s stop propagation flag.

The cancelBubble getter steps are to return true if this’s stop propagation flag is set; otherwise false.

The cancelBubble setter steps are to set this’s stop propagation flag if the given value is true; otherwise do nothing.

The stopImmediatePropagation() method steps are to set this’s stop propagation flag and this’s stop immediate propagation flag.

The bubbles and cancelable attributes must return the values they were initialized to.

To set the canceled flag, given an event event, if event’s cancelable attribute value is true and event’s in passive listener flag is unset, then set event’s canceled flag, and do nothing otherwise.

The returnValue getter steps are to return false if this’s canceled flag is set; otherwise true.

The returnValue setter steps are to set the canceled flag with this if the given value is false; otherwise do nothing.

The preventDefault() method steps are to set the canceled flag with this.

There are scenarios where invoking preventDefault() has no effect. User agents are encouraged to log the precise cause in a developer console, to aid debugging.

The defaultPrevented getter steps are to return true if this’s canceled flag is set; otherwise false.

The composed getter steps are to return true if this’s composed flag is set; otherwise false.

The isTrusted attribute must return the value it was initialized to. When an event is created the attribute must be initialized to false.

isTrusted is a convenience that indicates whether an event is dispatched by the user agent (as opposed to using dispatchEvent()). The sole legacy exception is click(), which causes the user agent to dispatch an event whose isTrusted attribute is initialized to false.

The timeStamp attribute must return the value it was initialized to.

To initialize an event, with type, bubbles, and cancelable, run these steps:

1. Set event’s initialized flag.

2. Unset event’s stop propagation flag, stop immediate propagation flag, and canceled flag.

3. Set event’s isTrusted attribute to false.

4. Set event’s target to null.

5. Set event’s type attribute to type.

6. Set event’s bubbles attribute to bubbles.

7. Set event’s cancelable attribute to cancelable.

The initEvent(type, bubbles, cancelable) method steps are:

1. If this’s dispatch flag is set, then return.

2. Initialize this with type, bubbles, and cancelable.

initEvent() is redundant with event constructors and incapable of setting composed. It has to be supported for legacy content.

2.3. Legacy extensions to the Window interface

partial interface Window {
  [Replaceable] readonly attribute (Event or undefined) event; // legacy
};

Each Window object has an associated current event (undefined or an Event object). Unless stated otherwise it is undefined.

The event getter steps are to return this’s current event.

Web developers are strongly encouraged to instead rely on the Event object passed to event listeners, as that will result in more portable code. This attribute is not available in workers or worklets, and is inaccurate for events dispatched in shadow trees.

2.4. Interface CustomEvent

[Exposed=*]
interface CustomEvent : Event {
  constructor(DOMString type, optional CustomEventInit eventInitDict = {});

  readonly attribute any detail;

  undefined initCustomEvent(DOMString type, optional boolean bubbles = false, optional boolean cancelable = false, optional any detail = null); // legacy
};

dictionary CustomEventInit : EventInit {
  any detail = null;
};

Events using the CustomEvent interface can be used to carry custom data.

event = new CustomEvent(type [, eventInitDict])

Works analogously to the constructor for Event except that the eventInitDict argument now allows for setting the detail attribute too.

event . detail

Returns any custom data event was created with. Typically used for synthetic events.

The detail attribute must return the value it was initialized to.

The initCustomEvent(type, bubbles, cancelable, detail) method steps are:

1. If this’s dispatch flag is set, then return.

2. Initialize this with type, bubbles, and cancelable.

3. Set this’s detail attribute to detail.

2.5. Constructing events

Specifications may define event constructing steps for all or some events. The algorithm is passed an event event and an EventInit eventInitDict as indicated in the inner event creation steps.

This construct can be used by Event subclasses that have a more complex structure than a simple 1:1 mapping between their initializing dictionary members and IDL attributes.

When a constructor of the Event interface, or of an interface that inherits from the Event interface, is invoked, these steps must be run, given the arguments type and eventInitDict:

1. Let event be the result of running the inner event creation steps with this interface, null, now, and eventInitDict.

2. Initialize event’s type attribute to type.

3. Return event.

To create an event using eventInterface, which must be either Event or an interface that inherits from it, and optionally given a realm realm, run these steps:

1. If realm is not given, then set it to null.

2. Let dictionary be the result of converting the JavaScript value undefined to the dictionary type accepted by eventInterface’s constructor. (This dictionary type will either be EventInit or a dictionary that inherits from it.)

   This does not work if members are required; see whatwg/dom#600.

3. Let event be the result of running the inner event creation steps with eventInterface, realm, the time of the occurrence that the event is signaling, and dictionary.

   In macOS the time of the occurrence for input actions is available via the timestamp property of NSEvent objects.

4. Initialize event’s isTrusted attribute to true.

5. Return event.

Create an event is meant to be used by other specifications which need to separately create and dispatch events, instead of simply firing them. It ensures the event’s attributes are initialized to the correct defaults.

The inner event creation steps, given an interface, realm, time, and dictionary, are as follows:

1. Let event be the result of creating a new object using eventInterface. If realm is non-null, then use that realm; otherwise, use the default behavior defined in Web IDL.

   As of the time of this writing Web IDL does not yet define any default behavior; see whatwg/webidl#135.

2. Set event’s initialized flag.

3. Initialize event’s timeStamp attribute to the relative high resolution coarse time given time and event’s relevant global object.

4. For each member → value in dictionary, if event has an attribute whose identifier is member, then initialize that attribute to value.

5. Run the event constructing steps with event and dictionary.

6. Return event.

2.6. Defining event interfaces

In general, when defining a new interface that inherits from Event please always ask feedback from the WHATWG or the W3C WebApps WG community.

The CustomEvent interface can be used as starting point. However, do not introduce any init*Event() methods as they are redundant with constructors. Interfaces that inherit from the Event interface that have such a method only have it for historical reasons.

2.7. Interface EventTarget

[Exposed=*]
interface EventTarget {
  constructor();

  undefined addEventListener(DOMString type, EventListener? callback, optional (AddEventListenerOptions or boolean) options = {});
  undefined removeEventListener(DOMString type, EventListener? callback, optional (EventListenerOptions or boolean) options = {});
  boolean dispatchEvent(Event event);
};

callback interface EventListener {
  undefined handleEvent(Event event);
};

dictionary EventListenerOptions {
  boolean capture = false;
};

dictionary AddEventListenerOptions : EventListenerOptions {
  boolean passive;
  boolean once = false;
  AbortSignal signal;
};

An EventTarget object represents a target to which an event can be dispatched when something has occurred.

Each EventTarget object has an associated event listener list (a list of zero or more event listeners). It is initially the empty list.

An event listener can be used to observe a specific event and consists of:

• type (a string)
• callback (null or an EventListener object)
• capture (a boolean, initially false)
• passive (null or a boolean, initially null)
• once (a boolean, initially false)
• signal (null or an AbortSignal object)
• removed (a boolean for bookkeeping purposes, initially false)

Although callback is an EventListener object, an event listener is a broader concept as can be seen above.

Each EventTarget object also has an associated get the parent algorithm, which takes an event event, and returns an EventTarget object. Unless specified otherwise it returns null.

Nodes, shadow roots, and documents override the get the parent algorithm.

Each EventTarget object can have an associated activation behavior algorithm. The activation behavior algorithm is passed an event, as indicated in the dispatch algorithm.

This exists because user agents perform certain actions for certain EventTarget objects, e.g., the area element, in response to synthetic MouseEvent events whose type attribute is click. Web compatibility prevented it from being removed and it is now the enshrined way of defining an activation of something. [HTML]

Each EventTarget object that has activation behavior, can additionally have both (not either) a legacy-pre-activation behavior algorithm and a legacy-canceled-activation behavior algorithm.

These algorithms only exist for checkbox and radio input elements and are not to be used for anything else. [HTML]

target = new EventTarget();

Creates a new EventTarget object, which can be used by developers to dispatch and listen for events.

target . addEventListener(type, callback [, options])

Appends an event listener for events whose type attribute value is type. The callback argument sets the callback that will be invoked when the event is dispatched.

The options argument sets listener-specific options. For compatibility this can be a boolean, in which case the method behaves exactly as if the value was specified as options’s capture.

When set to true, options’s capture prevents callback from being invoked when the event’s eventPhase attribute value is BUBBLING_PHASE. When false (or not present), callback will not be invoked when event’s eventPhase attribute value is CAPTURING_PHASE. Either way, callback will be invoked if event’s eventPhase attribute value is AT_TARGET.

When set to true, options’s passive indicates that the callback will not cancel the event by invoking preventDefault(). This is used to enable performance optimizations described in § 2.8 Observing event listeners.

When set to true, options’s once indicates that the callback will only be invoked once after which the event listener will be removed.

If an AbortSignal is passed for options’s signal, then the event listener will be removed when signal is aborted.

The event listener is appended to target’s event listener list and is not appended if it has the same type, callback, and capture.

target . removeEventListener(type, callback [, options])

Removes the event listener in target’s event listener list with the same type, callback, and options.

target . dispatchEvent(event)

Dispatches a synthetic event event to target and returns true if either event’s cancelable attribute value is false or its preventDefault() method was not invoked; otherwise false.

The new EventTarget() constructor steps are to do nothing.

Because of the defaults stated elsewhere, the returned EventTarget's get the parent algorithm will return null, and it will have no activation behavior, legacy-pre-activation behavior, or legacy-canceled-activation behavior.

In the future we could allow custom get the parent algorithms. Let us know if this would be useful for your programs. For now, all author-created EventTargets do not participate in a tree structure.

2.8. Observing event listeners

In general, developers do not expect the presence of an event listener to be observable. The impact of an event listener is determined by its callback. That is, a developer adding a no-op event listener would not expect it to have any side effects.

Unfortunately, some event APIs have been designed such that implementing them efficiently requires observing event listeners. This can make the presence of listeners observable in that even empty listeners can have a dramatic performance impact on the behavior of the application. For example, touch and wheel events which can be used to block asynchronous scrolling. In some cases this problem can be mitigated by specifying the event to be cancelable only when there is at least one non-passive listener. For example, non-passive TouchEvent listeners must block scrolling, but if all listeners are passive then scrolling can be allowed to start in parallel by making the TouchEvent uncancelable (so that calls to preventDefault() are ignored). So code dispatching an event is able to observe the absence of non-passive listeners, and use that to clear the cancelable property of the event being dispatched.

Ideally, any new event APIs are defined such that they do not need this property. (Use whatwg/dom for discussion.)

To legacy-obtain service worker fetch event listener callbacks given a ServiceWorkerGlobalScope global, run these steps. They return a list of EventListener objects.

1. Let callbacks be « ».

2. For each listener of global’s event listener list:

   1. If listener’s type is "fetch", and listener’s callback is not null, then append listener’s callback to callbacks.

3. Return callbacks.

2.9. Dispatching events

To dispatch an event to a target, with an optional legacy target override flag and an optional legacyOutputDidListenersThrowFlag, run these steps:

1. Set event’s dispatch flag.

2. Let targetOverride be target, if legacy target override flag is not given, and target’s associated Document otherwise. [HTML]

   legacy target override flag is only used by HTML and only when target is a Window object.

3. Let activationTarget be null.

4. Let relatedTarget be the result of retargeting event’s relatedTarget against target.

5. If target is not relatedTarget or target is event’s relatedTarget, then:

   1. Let touchTargets be a new list.

   2. For each touchTarget of event’s touch target list, append the result of retargeting touchTarget against target to touchTargets.

   3. Append to an event path with event, target, targetOverride, relatedTarget, touchTargets, and false.

   4. Let isActivationEvent be true, if event is a MouseEvent object and event’s type attribute is "click"; otherwise false.

   5. If isActivationEvent is true and target has activation behavior, then set activationTarget to target.

   6. Let slottable be target, if target is a slottable and is assigned, and null otherwise.

   7. Let slot-in-closed-tree be false.

   8. Let parent be the result of invoking target’s get the parent with event.

   9. While parent is non-null:

      1. If slottable is non-null:

         1. Assert: parent is a slot.

         2. Set slottable to null.

         3. If parent’s root is a shadow root whose mode is "closed", then set slot-in-closed-tree to true.

      2. If parent is a slottable and is assigned, then set slottable to parent.

      3. Let relatedTarget be the result of retargeting event’s relatedTarget against parent.

      4. Let touchTargets be a new list.

      5. For each touchTarget of event’s touch target list, append the result of retargeting touchTarget against parent to touchTargets.

      6. If parent is a Window object, or parent is a node and target’s root is a shadow-including inclusive ancestor of parent, then:

         1. If isActivationEvent is true, event’s bubbles attribute is true, activationTarget is null, and parent has activation behavior, then set activationTarget to parent.

         2. Append to an event path with event, parent, null, relatedTarget, touchTargets, and slot-in-closed-tree.

      7. Otherwise, if parent is relatedTarget, then set parent to null.

      8. Otherwise, set target to parent and then:

         1. If isActivationEvent is true, activationTarget is null, and target has activation behavior, then set activationTarget to target.

         2. Append to an event path with event, parent, target, relatedTarget, touchTargets, and slot-in-closed-tree.

      9. If parent is non-null, then set parent to the result of invoking parent’s get the parent with event.

      10. Set slot-in-closed-tree to false.

   10. Let clearTargetsStruct be the last struct in event’s path whose shadow-adjusted target is non-null.

   11. Let clearTargets be true if clearTargetsStruct’s shadow-adjusted target, clearTargetsStruct’s relatedTarget, or an EventTarget object in clearTargetsStruct’s touch target list is a node and its root is a shadow root; otherwise false.

   12. If activationTarget is non-null and activationTarget has legacy-pre-activation behavior, then run activationTarget’s legacy-pre-activation behavior.

   13. For each struct in event’s path, in reverse order:

       1. If struct’s shadow-adjusted target is non-null, then set event’s eventPhase attribute to AT_TARGET.

       2. Otherwise, set event’s eventPhase attribute to CAPTURING_PHASE.

       3. Invoke with struct, event, "capturing", and legacyOutputDidListenersThrowFlag if given.

   14. For each struct in event’s path:

       1. If struct’s shadow-adjusted target is non-null, then set event’s eventPhase attribute to AT_TARGET.

       2. Otherwise:

          1. If event’s bubbles attribute is false, then continue.

          2. Set event’s eventPhase attribute to BUBBLING_PHASE.

       3. Invoke with struct, event, "bubbling", and legacyOutputDidListenersThrowFlag if given.

6. Set event’s eventPhase attribute to NONE.

7. Set event’s currentTarget attribute to null.

8. Set event’s path to the empty list.

9. Unset event’s dispatch flag, stop propagation flag, and stop immediate propagation flag.

10. If clearTargets, then:

    1. Set event’s target to null.

    2. Set event’s relatedTarget to null.

    3. Set event’s touch target list to the empty list.

11. If activationTarget is non-null, then:

    1. If event’s canceled flag is unset, then run activationTarget’s activation behavior with event.

    2. Otherwise, if activationTarget has legacy-canceled-activation behavior, then run activationTarget’s legacy-canceled-activation behavior.

12. Return false if event’s canceled flag is set; otherwise true.

To append to an event path, given an event, invocationTarget, shadowAdjustedTarget, relatedTarget, touchTargets, and a slot-in-closed-tree, run these steps:

1. Let invocationTargetInShadowTree be false.

2. If invocationTarget is a node and its root is a shadow root, then set invocationTargetInShadowTree to true.

3. Let root-of-closed-tree be false.

4. If invocationTarget is a shadow root whose mode is "closed", then set root-of-closed-tree to true.

5. Append a new struct to event’s path whose invocation target is invocationTarget, invocation-target-in-shadow-tree is invocationTargetInShadowTree, shadow-adjusted target is shadowAdjustedTarget, relatedTarget is relatedTarget, touch target list is touchTargets, root-of-closed-tree is root-of-closed-tree, and slot-in-closed-tree is slot-in-closed-tree.

To invoke, given a struct, event, phase, and an optional legacyOutputDidListenersThrowFlag, run these steps:

1. Set event’s target to the shadow-adjusted target of the last struct in event’s path, that is either struct or preceding struct, whose shadow-adjusted target is non-null.

2. Set event’s relatedTarget to struct’s relatedTarget.

3. Set event’s touch target list to struct’s touch target list.

4. If event’s stop propagation flag is set, then return.

5. Initialize event’s currentTarget attribute to struct’s invocation target.

6. Let listeners be a clone of event’s currentTarget attribute value’s event listener list.

   This avoids event listeners added after this point from being run. Note that removal still has an effect due to the removed field.

7. Let invocationTargetInShadowTree be struct’s invocation-target-in-shadow-tree.

8. Let found be the result of running inner invoke with event, listeners, phase, invocationTargetInShadowTree, and legacyOutputDidListenersThrowFlag if given.

9. If found is false and event’s isTrusted attribute is true, then:

   1. Let originalEventType be event’s type attribute value.

   2. If event’s type attribute value is a match for any of the strings in the first column in the following table, set event’s type attribute value to the string in the second column on the same row as the matching string, and return otherwise.

      Event type	Legacy event type
      "animationend"	"webkitAnimationEnd"
      "animationiteration"	"webkitAnimationIteration"
      "animationstart"	"webkitAnimationStart"
      "transitionend"	"webkitTransitionEnd"

   3. Inner invoke with event, listeners, phase, invocationTargetInShadowTree, and legacyOutputDidListenersThrowFlag if given.

   4. Set event’s type attribute value to originalEventType.

To inner invoke, given an event, listeners, phase, invocationTargetInShadowTree, and an optional legacyOutputDidListenersThrowFlag, run these steps:

1. Let found be false.

2. For each listener in listeners, whose removed is false:

   1. If event’s type attribute value is not listener’s type, then continue.

   2. Set found to true.

   3. If phase is "capturing" and listener’s capture is false, then continue.

   4. If phase is "bubbling" and listener’s capture is true, then continue.

   5. If listener’s once is true, then remove listener from event’s currentTarget attribute value’s event listener list.

   6. Let global be listener callback’s associated realm’s global object.

   7. Let currentEvent be undefined.

   8. If global is a Window object, then:

      1. Set currentEvent to global’s current event.

      2. If invocationTargetInShadowTree is false, then set global’s current event to event.

   9. If listener’s passive is true, then set event’s in passive listener flag.

   10. Call a user object’s operation with listener’s callback, "handleEvent", « event », and event’s currentTarget attribute value. If this throws an exception, then:

       1. Report the exception.

       2. Set legacyOutputDidListenersThrowFlag if given.

          The legacyOutputDidListenersThrowFlag is only used by Indexed Database API. [INDEXEDDB]

   11. Unset event’s in passive listener flag.

   12. If global is a Window object, then set global’s current event to currentEvent.

   13. If event’s stop immediate propagation flag is set, then return found.

3. Return found.

2.10. Firing events

To fire an event named e at target, optionally using an eventConstructor, with a description of how IDL attributes are to be initialized, and a legacy target override flag, run these steps:

1. If eventConstructor is not given, then let eventConstructor be Event.

2. Let event be the result of creating an event given eventConstructor, in the relevant realm of target.

3. Initialize event’s type attribute to e.

4. Initialize any other IDL attributes of event as described in the invocation of this algorithm.

   This also allows for the isTrusted attribute to be set to false.

5. Return the result of dispatching event at target, with legacy target override flag set if set.

Fire in the context of DOM is short for creating, initializing, and dispatching an event. Fire an event makes that process easier to write down.

2.11. Action versus occurrence

An event signifies an occurrence, not an action. Phrased differently, it represents a notification from an algorithm and can be used to influence the future course of that algorithm (e.g., through invoking preventDefault()). Events must not be used as actions or initiators that cause some algorithm to start running. That is not what they are for.

This is called out here specifically because previous iterations of the DOM had a concept of "default actions" associated with events that gave folks all the wrong ideas. Events do not represent or cause actions, they can only be used to influence an ongoing one.

3. Aborting ongoing activities

Though promises do not have a built-in aborting mechanism, many APIs using them require abort semantics. AbortController is meant to support these requirements by providing an abort() method that toggles the state of a corresponding AbortSignal object. The API which wishes to support aborting can accept an AbortSignal object, and use its state to determine how to proceed.

APIs that rely upon AbortController are encouraged to respond to abort() by rejecting any unsettled promise with the AbortSignal's abort reason.

const controller = new AbortController();
const signal = controller.signal;

startSpinner();

doAmazingness({ ..., signal })
  .then(result => ...)
  .catch(err => {
    if (err.name == 'AbortError') return;
    showUserErrorMessage();
  })
  .then(() => stopSpinner());

// …

controller.abort();

function doAmazingness({signal}) {
  return new Promise((resolve, reject) => {
    signal.throwIfAborted();

    // Begin doing amazingness, and call resolve(result) when done.
    // But also, watch for signals:
    signal.addEventListener('abort', () => {
      // Stop doing amazingness, and:
      reject(signal.reason);
    });
  });
}

APIs that do not return promises can either react in an equivalent manner or opt to not surface the AbortSignal's abort reason at all. addEventListener() is an example of an API where the latter made sense.

APIs that require more granular control could extend both AbortController and AbortSignal objects according to their needs.

3.1. Interface AbortController

[Exposed=*]
interface AbortController {
  constructor();

  [SameObject] readonly attribute AbortSignal signal;

  undefined abort(optional any reason);
};

controller = new AbortController()

Returns a new controller whose signal is set to a newly created AbortSignal object.

controller . signal

Returns the AbortSignal object associated with this object.

controller . abort(reason)

Invoking this method will store reason in this object’s AbortSignal's abort reason, and signal to any observers that the associated activity is to be aborted. If reason is undefined, then an "AbortError" DOMException will be stored.

An AbortController object has an associated signal (an AbortSignal object).

The signal getter steps are to return this’s signal.

3.2. Interface AbortSignal

[Exposed=*]
interface AbortSignal : EventTarget {
  [NewObject] static AbortSignal abort(optional any reason);
  [Exposed=(Window,Worker), NewObject] static AbortSignal timeout([EnforceRange] unsigned long long milliseconds);
  [NewObject] static AbortSignal _any(sequence<AbortSignal> signals);

  readonly attribute boolean aborted;
  readonly attribute any reason;
  undefined throwIfAborted();

  attribute EventHandler onabort;
};

AbortSignal . abort(reason)

Returns an AbortSignal instance whose abort reason is set to reason if not undefined; otherwise to an "AbortError" DOMException.

AbortSignal . any(signals)

Returns an AbortSignal instance which will be aborted once any of signals is aborted. Its abort reason will be set to whichever one of signals caused it to be aborted.

AbortSignal . timeout(milliseconds)

Returns an AbortSignal instance which will be aborted in milliseconds milliseconds. Its abort reason will be set to a "TimeoutError" DOMException.

signal . aborted

Returns true if signal’s AbortController has signaled to abort; otherwise false.

signal . reason

Returns signal’s abort reason.

signal . throwIfAborted()

Throws signal’s abort reason, if signal’s AbortController has signaled to abort; otherwise, does nothing.

An AbortSignal object has an associated abort reason (a JavaScript value), which is initially undefined.

An AbortSignal object has associated abort algorithms, (a set of algorithms which are to be executed when it is aborted), which is initially empty.

The abort algorithms enable APIs with complex requirements to react in a reasonable way to abort(). For example, a given API’s abort reason might need to be propagated to a cross-thread environment, such as a service worker.

An AbortSignal object has a dependent (a boolean), which is initially false.

An AbortSignal object has associated source signals (a weak set of AbortSignal objects that the object is dependent on for its aborted state), which is initially empty.

An AbortSignal object has associated dependent signals (a weak set of AbortSignal objects that are dependent on the object for their aborted state), which is initially empty.

The aborted getter steps are to return true if this is aborted; otherwise false.

The reason getter steps are to return this’s abort reason.

The throwIfAborted() method steps are to throw this’s abort reason, if this is aborted.

async function waitForCondition(func, targetValue, { signal } = {}) {
  while (true) {
    signal?.throwIfAborted();

    const result = await func();
    if (result === targetValue) {
      return;
    }
  }
}

The onabort attribute is an event handler IDL attribute for the onabort event handler, whose event handler event type is abort.

Changes to an AbortSignal object represent the wishes of the corresponding AbortController object, but an API observing the AbortSignal object can choose to ignore them. For instance, if the operation has already completed.

An AbortSignal object is aborted when its abort reason is not undefined.

3.2.1. Garbage collection

A non-aborted dependent AbortSignal object must not be garbage collected while its source signals is non-empty and it has registered event listeners for its abort event or its abort algorithms is non-empty.

3.3. Using AbortController and AbortSignal objects in APIs

Any web platform API using promises to represent operations that can be aborted must adhere to the following:

• Accept AbortSignal objects through a signal dictionary member.
• Convey that the operation got aborted by rejecting the promise with AbortSignal object’s abort reason.
• Reject immediately if the AbortSignal is already aborted, otherwise:
• Use the abort algorithms mechanism to observe changes to the AbortSignal object and do so in a manner that does not lead to clashes with other observers.

APIs not using promises should still adhere to the above as much as possible.

4. Nodes

4.1. Introduction to "The DOM"

In its original sense, "The DOM" is an API for accessing and manipulating documents (in particular, HTML and XML documents). In this specification, the term "document" is used for any markup-based resource, ranging from short static documents to long essays or reports with rich multimedia, as well as to fully-fledged interactive applications.

Each such document is represented as a node tree. Some of the nodes in a tree can have children, while others are always leaves.

To illustrate, consider this HTML document:

<!DOCTYPE html>
<html class=e>
 <head><title>Aliens?</title></head>
 <body>Why yes.</body>
</html>

It is represented as follows:

• Document
  • Doctype: html
  • Element: html class="e"
    • Element: head
      • Element: title
        • Text: Aliens?
    • Text: ⏎␣
    • Element: body
      • Text: Why yes.⏎

Note that, due to the magic that is HTML parsing, not all ASCII whitespace were turned into Text nodes, but the general concept is clear. Markup goes in, a tree of nodes comes out.

The most excellent Live DOM Viewer can be used to explore this matter in more detail.

4.2. Node tree

Nodes are objects that implement Node. Nodes participate in a tree, which is known as the node tree.

For brevity, this specification refers to an object that implements Node and an inherited interface NodeInterface, as a NodeInterface node.

A node tree is constrained as follows, expressed as a relationship between a node and its potential children:

Document

In tree order:

1. Zero or more ProcessingInstruction or Comment nodes.

2. Optionally one DocumentType node.

3. Zero or more ProcessingInstruction or Comment nodes.

4. Optionally one Element node.

5. Zero or more ProcessingInstruction or Comment nodes.

DocumentFragment

Element

Zero or more Element or CharacterData nodes.

DocumentType

CharacterData

Attr

No children.

Attr nodes participate in a tree for historical reasons; they never have a (non-null) parent or any children and are therefore alone in a tree.

To determine the length of a node node, run these steps:

1. If node is a DocumentType or Attr node, then return 0.

2. If node is a CharacterData node, then return node’s data’s length.

3. Return the number of node’s children.

A node is considered empty if its length is 0.

4.2.1. Document tree

A document tree is a node tree whose root is a document.

The document element of a document is the element whose parent is that document, if it exists; otherwise null.

Per the node tree constraints, there can be only one such element.

An element is in a document tree if its root is a document.

An element is in a document if it is in a document tree. The term in a document is no longer supposed to be used. It indicates that the standard using it has not been updated to account for shadow trees.

4.2.2. Shadow tree

A shadow tree is a node tree whose root is a shadow root.

A shadow root is always attached to another node tree through its host. A shadow tree is therefore never alone. The node tree of a shadow root’s host is sometimes referred to as the light tree.

A shadow tree’s corresponding light tree can be a shadow tree itself.

An element is connected if its shadow-including root is a document.

4.2.2.1. Slots

A shadow tree contains zero or more elements that are slots.

A slot can only be created through HTML’s slot element.

A slot has an associated name (a string). Unless stated otherwise it is the empty string.

Use these attribute change steps to update a slot’s name:

1. If element is a slot, localName is name, and namespace is null, then:

   1. If value is oldValue, then return.

   2. If value is null and oldValue is the empty string, then return.

   3. If value is the empty string and oldValue is null, then return.

   4. If value is null or the empty string, then set element’s name to the empty string.

   5. Otherwise, set element’s name to value.

   6. Run assign slottables for a tree with element’s root.

The first slot in a shadow tree, in tree order, whose name is the empty string, is sometimes known as the "default slot".

A slot has an associated assigned nodes (a list of slottables). Unless stated otherwise it is empty.

4.2.2.2. Slottables

Element and Text nodes are slottables.

A slot can be a slottable.

A slottable has an associated name (a string). Unless stated otherwise it is the empty string.

Use these attribute change steps to update a slottable’s name:

1. If localName is slot and namespace is null, then:

   1. If value is oldValue, then return.

   2. If value is null and oldValue is the empty string, then return.

   3. If value is the empty string and oldValue is null, then return.

   4. If value is null or the empty string, then set element’s name to the empty string.

   5. Otherwise, set element’s name to value.

   6. If element is assigned, then run assign slottables for element’s assigned slot.

   7. Run assign a slot for element.

A slottable has an associated assigned slot (null or a slot). Unless stated otherwise it is null. A slottable is assigned if its assigned slot is non-null.

A slottable has an associated manual slot assignment (null or a slot). Unless stated otherwise, it is null.

A slottable’s manual slot assignment can be implemented using a weak reference to the slot, because this variable is not directly accessible from script.

4.2.2.3. Finding slots and slottables

To find a slot for a given slottable slottable and an optional open flag (unset unless stated otherwise), run these steps:

1. If slottable’s parent is null, then return null.

2. Let shadow be slottable’s parent’s shadow root.

3. If shadow is null, then return null.

4. If the open flag is set and shadow’s mode is not "open", then return null.

5. If shadow’s slot assignment is "manual", then return the slot in shadow’s descendants whose manually assigned nodes contains slottable, if any; otherwise null.

6. Return the first slot in tree order in shadow’s descendants whose name is slottable’s name, if any; otherwise null.

To find slottables for a given slot slot, run these steps:

1. Let result be an empty list.

2. Let root be slot’s root.

3. If root is not a shadow root, then return result.

4. Let host be root’s host.

5. If root’s slot assignment is "manual", then:

   1. Let result be « ».

   2. For each slottable slottable of slot’s manually assigned nodes, if slottable’s parent is host, append slottable to result.

6. Otherwise, for each slottable child slottable of host, in tree order:

   1. Let foundSlot be the result of finding a slot given slottable.

   2. If foundSlot is slot, then append slottable to result.

7. Return result.

To find flattened slottables for a given slot slot, run these steps:

1. Let result be an empty list.

2. If slot’s root is not a shadow root, then return result.

3. Let slottables be the result of finding slottables given slot.

4. If slottables is the empty list, then append each slottable child of slot, in tree order, to slottables.

5. For each node in slottables:

   1. If node is a slot whose root is a shadow root, then:

      1. Let temporaryResult be the result of finding flattened slottables given node.

      2. Append each slottable in temporaryResult, in order, to result.

   2. Otherwise, append node to result.

6. Return result.

4.2.2.4. Assigning slottables and slots

To assign slottables for a slot slot, run these steps:

1. Let slottables be the result of finding slottables for slot.

2. If slottables and slot’s assigned nodes are not identical, then run signal a slot change for slot.

3. Set slot’s assigned nodes to slottables.

4. For each slottable in slottables, set slottable’s assigned slot to slot.

To assign slottables for a tree, given a node root, run assign slottables for each slot slot in root’s inclusive descendants, in tree order.

To assign a slot, given a slottable slottable, run these steps:

1. Let slot be the result of finding a slot with slottable.

2. If slot is non-null, then run assign slottables for slot.

4.2.2.5. Signaling slot change

Each similar-origin window agent has signal slots (a set of slots), which is initially empty. [HTML]

To signal a slot change, for a slot slot, run these steps:

1. Append slot to slot’s relevant agent’s signal slots.

2. Queue a mutation observer microtask.

4.2.3. Mutation algorithms

To ensure pre-insertion validity of a node into a parent before a child, run these steps:

1. If parent is not a Document, DocumentFragment, or Element node, then throw a "HierarchyRequestError" DOMException.

2. If node is a host-including inclusive ancestor of parent, then throw a "HierarchyRequestError" DOMException.

3. If child is non-null and its parent is not parent, then throw a "NotFoundError" DOMException.

4. If node is not a DocumentFragment, DocumentType, Element, or CharacterData node, then throw a "HierarchyRequestError" DOMException.

5. If either node is a Text node and parent is a document, or node is a doctype and parent is not a document, then throw a "HierarchyRequestError" DOMException.

6. If parent is a document, and any of the statements below, switched on the interface node implements, are true, then throw a "HierarchyRequestError" DOMException.

   DocumentFragment

   If node has more than one element child or has a Text node child.

   Otherwise, if node has one element child and either parent has an element child, child is a doctype, or child is non-null and a doctype is following child.

   Element

   parent has an element child, child is a doctype, or child is non-null and a doctype is following child.

   DocumentType

   parent has a doctype child, child is non-null and an element is preceding child, or child is null and parent has an element child.

To pre-insert a node into a parent before a child, run these steps:

1. Ensure pre-insertion validity of node into parent before child.

2. Let referenceChild be child.

3. If referenceChild is node, then set referenceChild to node’s next sibling.

4. Insert node into parent before referenceChild.

5. Return node.

Specifications may define insertion steps for all or some nodes. The algorithm is passed insertedNode, as indicated in the insert algorithm below.

Specifications may define children changed steps for all or some nodes. The algorithm is passed no argument and is called from insert, remove, and replace data.

To insert a node into a parent before a child, with an optional suppress observers flag, run these steps:

1. Let nodes be node’s children, if node is a DocumentFragment node; otherwise « node ».

2. Let count be nodes’s size.

3. If count is 0, then return.

4. If node is a DocumentFragment node, then:

   1. Remove its children with the suppress observers flag set.

   2. Queue a tree mutation record for node with « », nodes, null, and null.

      This step intentionally does not pay attention to the suppress observers flag.

5. If child is non-null, then:

   1. For each live range whose start node is parent and start offset is greater than child’s index, increase its start offset by count.

   2. For each live range whose end node is parent and end offset is greater than child’s index, increase its end offset by count.

6. Let previousSibling be child’s previous sibling or parent’s last child if child is null.

7. For each node in nodes, in tree order:

   1. Adopt node into parent’s node document.

   2. If child is null, then append node to parent’s children.

   3. Otherwise, insert node into parent’s children before child’s index.

   4. If parent is a shadow host whose shadow root’s slot assignment is "named" and node is a slottable, then assign a slot for node.

   5. If parent’s root is a shadow root, and parent is a slot whose assigned nodes is the empty list, then run signal a slot change for parent.

   6. Run assign slottables for a tree with node’s root.

   7. For each shadow-including inclusive descendant inclusiveDescendant of node, in shadow-including tree order:

      1. Run the insertion steps with inclusiveDescendant.

      2. If inclusiveDescendant is connected, then:

         1. If inclusiveDescendant is custom, then enqueue a custom element callback reaction with inclusiveDescendant, callback name "connectedCallback", and an empty argument list.

         2. Otherwise, try to upgrade inclusiveDescendant.

            If this successfully upgrades inclusiveDescendant, its connectedCallback will be enqueued automatically during the upgrade an element algorithm.

8. If suppress observers flag is unset, then queue a tree mutation record for parent with nodes, « », previousSibling, and child.

9. Run the children changed steps for parent.

To append a node to a parent, pre-insert node into parent before null.

To replace a child with node within a parent, run these steps:

1. If parent is not a Document, DocumentFragment, or Element node, then throw a "HierarchyRequestError" DOMException.

2. If node is a host-including inclusive ancestor of parent, then throw a "HierarchyRequestError" DOMException.

3. If child’s parent is not parent, then throw a "NotFoundError" DOMException.

4. If node is not a DocumentFragment, DocumentType, Element, or CharacterData node, then throw a "HierarchyRequestError" DOMException.

5. If either node is a Text node and parent is a document, or node is a doctype and parent is not a document, then throw a "HierarchyRequestError" DOMException.

6. If parent is a document, and any of the statements below, switched on the interface node implements, are true, then throw a "HierarchyRequestError" DOMException.

   DocumentFragment

   If node has more than one element child or has a Text node child.

   Otherwise, if node has one element child and either parent has an element child that is not child or a doctype is following child.

   Element

   parent has an element child that is not child or a doctype is following child.

   DocumentType

   parent has a doctype child that is not child, or an element is preceding child.

   The above statements differ from the pre-insert algorithm.

7. Let referenceChild be child’s next sibling.

8. If referenceChild is node, then set referenceChild to node’s next sibling.

9. Let previousSibling be child’s previous sibling.

10. Let removedNodes be the empty set.

11. If child’s parent is non-null, then:

    1. Set removedNodes to « child ».

    2. Remove child with the suppress observers flag set.

    The above can only be false if child is node.

12. Let nodes be node’s children if node is a DocumentFragment node; otherwise « node ».

13. Insert node into parent before referenceChild with the suppress observers flag set.

14. Queue a tree mutation record for parent with nodes, removedNodes, previousSibling, and referenceChild.

15. Return child.

To replace all with a node within a parent, run these steps:

1. Let removedNodes be parent’s children.

2. Let addedNodes be the empty set.

3. If node is a DocumentFragment node, then set addedNodes to node’s children.

4. Otherwise, if node is non-null, set addedNodes to « node ».

5. Remove all parent’s children, in tree order, with the suppress observers flag set.

6. If node is non-null, then insert node into parent before null with the suppress observers flag set.

7. If either addedNodes or removedNodes is not empty, then queue a tree mutation record for parent with addedNodes, removedNodes, null, and null.

This algorithm does not make any checks with regards to the node tree constraints. Specification authors need to use it wisely.

To pre-remove a child from a parent, run these steps:

1. If child’s parent is not parent, then throw a "NotFoundError" DOMException.

2. Remove child.

3. Return child.

Specifications may define removing steps for all or some nodes. The algorithm is passed a node removedNode and a node-or-null oldParent, as indicated in the remove algorithm below.

To remove a node node, with an optional suppress observers flag, run these steps:

1. Let parent be node’s parent.

2. Assert: parent is non-null.

3. Let index be node’s index.

4. For each live range whose start node is an inclusive descendant of node, set its start to (parent, index).

5. For each live range whose end node is an inclusive descendant of node, set its end to (parent, index).

6. For each live range whose start node is parent and start offset is greater than index, decrease its start offset by 1.

7. For each live range whose end node is parent and end offset is greater than index, decrease its end offset by 1.

8. For each NodeIterator object iterator whose root’s node document is node’s node document, run the NodeIterator pre-removing steps given node and iterator.

9. Let oldPreviousSibling be node’s previous sibling.

10. Let oldNextSibling be node’s next sibling.

11. Remove node from its parent’s children.

12. If node is assigned, then run assign slottables for node’s assigned slot.

13. If parent’s root is a shadow root, and parent is a slot whose assigned nodes is the empty list, then run signal a slot change for parent.

14. If node has an inclusive descendant that is a slot, then:

    1. Run assign slottables for a tree with parent’s root.

    2. Run assign slottables for a tree with node.

15. Run the removing steps with node and parent.

16. Let isParentConnected be parent’s connected.

17. If node is custom and isParentConnected is true, then enqueue a custom element callback reaction with node, callback name "disconnectedCallback", and an empty argument list.

    It is intentional for now that custom elements do not get parent passed. This might change in the future if there is a need.

18. For each shadow-including descendant descendant of node, in shadow-including tree order, then:

    1. Run the removing steps with descendant and null.

    2. If descendant is custom and isParentConnected is true, then enqueue a custom element callback reaction with descendant, callback name "disconnectedCallback", and an empty argument list.

19. For each inclusive ancestor inclusiveAncestor of parent, and then for each registered of inclusiveAncestor’s registered observer list, if registered’s options["subtree"] is true, then append a new transient registered observer whose observer is registered’s observer, options is registered’s options, and source is registered to node’s registered observer list.

20. If suppress observers flag is unset, then queue a tree mutation record for parent with « », « node », oldPreviousSibling, and oldNextSibling.

21. Run the children changed steps for parent.

4.2.4. Mixin NonElementParentNode

Web compatibility prevents the getElementById() method from being exposed on elements (and therefore on ParentNode).

interface mixin NonElementParentNode {
  Element? getElementById(DOMString elementId);
};
Document includes NonElementParentNode;
DocumentFragment includes NonElementParentNode;

node . getElementById(elementId)

Returns the first element within node’s descendants whose ID is elementId.

The getElementById(elementId) method steps are to return the first element, in tree order, within this’s descendants, whose ID is elementId; otherwise, if there is no such element, null.

4.2.5. Mixin DocumentOrShadowRoot

interface mixin DocumentOrShadowRoot {
};
Document includes DocumentOrShadowRoot;
ShadowRoot includes DocumentOrShadowRoot;

The DocumentOrShadowRoot mixin is expected to be used by other standards that want to define APIs shared between documents and shadow roots.

4.2.6. Mixin ParentNode

To convert nodes into a node, given nodes and document, run these steps:

1. Let node be null.

2. Replace each string in nodes with a new Text node whose data is the string and node document is document.

3. If nodes contains one node, then set node to nodes[0].

4. Otherwise, set node to a new DocumentFragment node whose node document is document, and then append each node in nodes, if any, to it.

5. Return node.

interface mixin ParentNode {
  [SameObject] readonly attribute HTMLCollection children;
  readonly attribute Element? firstElementChild;
  readonly attribute Element? lastElementChild;
  readonly attribute unsigned long childElementCount;

  [CEReactions, Unscopable] undefined prepend((Node or DOMString)... nodes);
  [CEReactions, Unscopable] undefined append((Node or DOMString)... nodes);
  [CEReactions, Unscopable] undefined replaceChildren((Node or DOMString)... nodes);

  Element? querySelector(DOMString selectors);
  [NewObject] NodeList querySelectorAll(DOMString selectors);
};
Document includes ParentNode;
DocumentFragment includes ParentNode;
Element includes ParentNode;

collection = node . children

Returns the child elements.

element = node . firstElementChild

Returns the first child that is an element; otherwise null.

element = node . lastElementChild

Returns the last child that is an element; otherwise null.

node . prepend(nodes)

Inserts nodes before the first child of node, while replacing strings in nodes with equivalent Text nodes.

Throws a "HierarchyRequestError" DOMException if the constraints of the node tree are violated.

node . append(nodes)

Inserts nodes after the last child of node, while replacing strings in nodes with equivalent Text nodes.

Throws a "HierarchyRequestError" DOMException if the constraints of the node tree are violated.

node . replaceChildren(nodes)

Replace all children of node with nodes, while replacing strings in nodes with equivalent Text nodes.

Throws a "HierarchyRequestError" DOMException if the constraints of the node tree are violated.

node . querySelector(selectors)

Returns the first element that is a descendant of node that matches selectors.

node . querySelectorAll(selectors)

Returns all element descendants of node that match selectors.

The children getter steps are to return an HTMLCollection collection rooted at this matching only element children.

The firstElementChild getter steps are to return the first child that is an element; otherwise null.

The lastElementChild getter steps are to return the last child that is an element; otherwise null.

The childElementCount getter steps are to return the number of children of this that are elements.

The prepend(nodes) method steps are:

1. Let node be the result of converting nodes into a node given nodes and this’s node document.

2. Pre-insert node into this before this’s first child.

The append(nodes) method steps are:

1. Let node be the result of converting nodes into a node given nodes and this’s node document.

2. Append node to this.

The replaceChildren(nodes) method steps are:

1. Let node be the result of converting nodes into a node given nodes and this’s node document.

2. Ensure pre-insertion validity of node into this before null.

3. Replace all with node within this.

The querySelector(selectors) method steps are to return the first result of running scope-match a selectors string selectors against this, if the result is not an empty list; otherwise null.

The querySelectorAll(selectors) method steps are to return the static result of running scope-match a selectors string selectors against this.

4.2.7. Mixin NonDocumentTypeChildNode

Web compatibility prevents the previousElementSibling and nextElementSibling attributes from being exposed on doctypes (and therefore on ChildNode).

interface mixin NonDocumentTypeChildNode {
  readonly attribute Element? previousElementSibling;
  readonly attribute Element? nextElementSibling;
};
Element includes NonDocumentTypeChildNode;
CharacterData includes NonDocumentTypeChildNode;

element = node . previousElementSibling

Returns the first preceding sibling that is an element; otherwise null.

element = node . nextElementSibling

Returns the first following sibling that is an element; otherwise null.

The previousElementSibling getter steps are to return the first preceding sibling that is an element; otherwise null.

The nextElementSibling getter steps are to return the first following sibling that is an element; otherwise null.

4.2.8. Mixin ChildNode

interface mixin ChildNode {
  [CEReactions, Unscopable] undefined before((Node or DOMString)... nodes);
  [CEReactions, Unscopable] undefined after((Node or DOMString)... nodes);
  [CEReactions, Unscopable] undefined replaceWith((Node or DOMString)... nodes);
  [CEReactions, Unscopable] undefined remove();
};
DocumentType includes ChildNode;
Element includes ChildNode;
CharacterData includes ChildNode;

node . before(...nodes)

Inserts nodes just before node, while replacing strings in nodes with equivalent Text nodes.

Throws a "HierarchyRequestError" DOMException if the constraints of the node tree are violated.

node . after(...nodes)

Inserts nodes just after node, while replacing strings in nodes with equivalent Text nodes.

Throws a "HierarchyRequestError" DOMException if the constraints of the node tree are violated.

node . replaceWith(...nodes)

Replaces node with nodes, while replacing strings in nodes with equivalent Text nodes.

Throws a "HierarchyRequestError" DOMException if the constraints of the node tree are violated.

node . remove()

Removes node.

The before(nodes) method steps are:

1. Let parent be this’s parent.

2. If parent is null, then return.

3. Let viablePreviousSibling be this’s first preceding sibling not in nodes; otherwise null.

4. Let node be the result of converting nodes into a node, given nodes and this’s node document.

5. If viablePreviousSibling is null, then set it to parent’s first child; otherwise to viablePreviousSibling’s next sibling.

6. Pre-insert node into parent before viablePreviousSibling.

The after(nodes) method steps are:

1. Let parent be this’s parent.

2. If parent is null, then return.

3. Let viableNextSibling be this’s first following sibling not in nodes; otherwise null.

4. Let node be the result of converting nodes into a node, given nodes and this’s node document.

5. Pre-insert node into parent before viableNextSibling.

The replaceWith(nodes) method steps are:

1. Let parent be this’s parent.

2. If parent is null, then return.

3. Let viableNextSibling be this’s first following sibling not in nodes; otherwise null.

4. Let node be the result of converting nodes into a node, given nodes and this’s node document.

5. If this’s parent is parent, replace this with node within parent.

   This could have been inserted into node.

6. Otherwise, pre-insert node into parent before viableNextSibling.

The remove() method steps are:

1. If this’s parent is null, then return.

2. Remove this.

4.2.9. Mixin Slottable

interface mixin Slottable {
  readonly attribute HTMLSlotElement? assignedSlot;
};
Element includes Slottable;
Text includes Slottable;

The assignedSlot getter steps are to return the result of find a slot given this and with the open flag set.

4.2.10. Old-style collections: NodeList and HTMLCollection

A collection is an object that represents a list of nodes. A collection can be either live or static. Unless otherwise stated, a collection must be live.

If a collection is live, then the attributes and methods on that object must operate on the actual underlying data, not a snapshot of the data.

When a collection is created, a filter and a root are associated with it.

The collection then represents a view of the subtree rooted at the collection’s root, containing only nodes that match the given filter. The view is linear. In the absence of specific requirements to the contrary, the nodes within the collection must be sorted in tree order.

4.2.10.1. Interface NodeList

A NodeList object is a collection of nodes.

[Exposed=Window]
interface NodeList {
  getter Node? item(unsigned long index);
  readonly attribute unsigned long length;
  iterable<Node>;
};

collection . length

Returns the number of nodes in the collection.

element = collection . item(index)

element = collection[index]

Returns the node with index index from the collection. The nodes are sorted in tree order.

4.2.10.2. Interface HTMLCollection

[Exposed=Window, LegacyUnenumerableNamedProperties]
interface HTMLCollection {
  readonly attribute unsigned long length;
  getter Element? item(unsigned long index);
  getter Element? namedItem(DOMString name);
};

An HTMLCollection object is a collection of elements.

HTMLCollection is a historical artifact we cannot rid the web of. While developers are of course welcome to keep using it, new API standard designers ought not to use it (use sequence<T> in IDL instead).

collection . length

Returns the number of elements in the collection.

element = collection . item(index)

element = collection[index]

Returns the element with index index from the collection. The elements are sorted in tree order.

element = collection . namedItem(name)

element = collection[name]

Returns the first element with ID or name name from the collection.

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

The length getter steps are to return the number of nodes represented by the collection.

The item(index) method steps are to return the index^th element in the collection. If there is no index^th element in the collection, then the method must return null.

The supported property names are the values from the list returned by these steps:

1. Let result be an empty list.

2. For each element represented by the collection, in tree order:

   1. If element has an ID which is not in result, append element’s ID to result.

   2. If element is in the HTML namespace and has a name attribute whose value is neither the empty string nor is in result, append element’s name attribute value to result.

3. Return result.

The namedItem(key) method steps are:

1. If key is the empty string, return null.

2. Return the first element in the collection for which at least one of the following is true:

   • it has an ID which is key;
   • it is in the HTML namespace and has a name attribute whose value is key;

   or null if there is no such element.

4.3. Mutation observers

Each similar-origin window agent has a mutation observer microtask queued (a boolean), which is initially false. [HTML]

Each similar-origin window agent also has pending mutation observers (a set of zero or more MutationObserver objects), which is initially empty.

To queue a mutation observer microtask, run these steps:

1. If the surrounding agent’s mutation observer microtask queued is true, then return.

2. Set the surrounding agent’s mutation observer microtask queued to true.

3. Queue a microtask to notify mutation observers.

To notify mutation observers, run these steps:

1. Set the surrounding agent’s mutation observer microtask queued to false.

2. Let notifySet be a clone of the surrounding agent’s pending mutation observers.

3. Empty the surrounding agent’s pending mutation observers.

4. Let signalSet be a clone of the surrounding agent’s signal slots.

5. Empty the surrounding agent’s signal slots.

6. For each mo of notifySet:

   1. Let records be a clone of mo’s record queue.

   2. Empty mo’s record queue.

   3. For each node of mo’s node list, remove all transient registered observers whose observer is mo from node’s registered observer list.

   4. If records is not empty, then invoke mo’s callback with « records, mo », and mo. If this throws an exception, catch it, and report the exception.

7. For each slot of signalSet, fire an event named slotchange, with its bubbles attribute set to true, at slot.

Each node has a registered observer list (a list of zero or more registered observers), which is initially empty.

A registered observer consists of an observer (a MutationObserver object) and options (a MutationObserverInit dictionary).

A transient registered observer is a registered observer that also consists of a source (a registered observer).

Transient registered observers are used to track mutations within a given node’s descendants after node has been removed so they do not get lost when subtree is set to true on node’s parent.

4.3.1. Interface MutationObserver

[Exposed=Window]
interface MutationObserver {
  constructor(MutationCallback callback);

  undefined observe(Node target, optional MutationObserverInit options = {});
  undefined disconnect();
  sequence<MutationRecord> takeRecords();
};

callback MutationCallback = undefined (sequence<MutationRecord> mutations, MutationObserver observer);

dictionary MutationObserverInit {
  boolean childList = false;
  boolean attributes;
  boolean characterData;
  boolean subtree = false;
  boolean attributeOldValue;
  boolean characterDataOldValue;
  sequence<DOMString> attributeFilter;
};

A MutationObserver object can be used to observe mutations to the tree of nodes.

Each MutationObserver object has these associated concepts:

• A callback set on creation.
• A node list (a list of weak references to nodes), which is initially empty.
• A record queue (a queue of zero or more MutationRecord objects), which is initially empty.

observer = new MutationObserver(callback)

Constructs a MutationObserver object and sets its callback to callback. The callback is invoked with a list of MutationRecord objects as first argument and the constructed MutationObserver object as second argument. It is invoked after nodes registered with the observe() method, are mutated.

observer . observe(target, options)

Instructs the user agent to observe a given target (a node) and report any mutations based on the criteria given by options (an object).

The options argument allows for setting mutation observation options via object members. These are the object members that can be used:

childList

Set to true if mutations to target’s children are to be observed.

attributes

Set to true if mutations to target’s attributes are to be observed. Can be omitted if attributeOldValue or attributeFilter is specified.

characterData

Set to true if mutations to target’s data are to be observed. Can be omitted if characterDataOldValue is specified.

subtree

Set to true if mutations to not just target, but also target’s descendants are to be observed.

attributeOldValue

Set to true if attributes is true or omitted and target’s attribute value before the mutation needs to be recorded.

characterDataOldValue

Set to true if characterData is set to true or omitted and target’s data before the mutation needs to be recorded.

attributeFilter

Set to a list of attribute local names (without namespace) if not all attribute mutations need to be observed and attributes is true or omitted.

observer . disconnect()

Stops observer from observing any mutations. Until the observe() method is used again, observer’s callback will not be invoked.

observer . takeRecords()

Empties the record queue and returns what was in there.

The new MutationObserver(callback) constructor steps are to set this’s callback to callback.

The observe(target, options) method steps are:

1. If either options["attributeOldValue"] or options["attributeFilter"] exists, and options["attributes"] does not exist, then set options["attributes"] to true.

2. If options["characterDataOldValue"] exists and options["characterData"] does not exist, then set options["characterData"] to true.

3. If none of options["childList"], options["attributes"], and options["characterData"] is true, then throw a TypeError.

4. If options["attributeOldValue"] is true and options["attributes"] is false, then throw a TypeError.

5. If options["attributeFilter"] is present and options["attributes"] is false, then throw a TypeError.

6. If options["characterDataOldValue"] is true and options["characterData"] is false, then throw a TypeError.

7. For each registered of target’s registered observer list, if registered’s observer is this:

   1. For each node of this’s node list, remove all transient registered observers whose source is registered from node’s registered observer list.

   2. Set registered’s options to options.

8. Otherwise:

   1. Append a new registered observer whose observer is this and options is options to target’s registered observer list.

   2. Append a weak reference to target to this’s node list.

The disconnect() method steps are:

1. For each node of this’s node list, remove any registered observer from node’s registered observer list for which this is the observer.

2. Empty this’s record queue.

The takeRecords() method steps are:

1. Let records be a clone of this’s record queue.

2. Empty this’s record queue.

3. Return records.

4.3.2. Queuing a mutation record

To queue a mutation record of type for target with name, namespace, oldValue, addedNodes, removedNodes, previousSibling, and nextSibling, run these steps:

1. Let interestedObservers be an empty map.

2. Let nodes be the inclusive ancestors of target.

3. For each node in nodes, and then for each registered of node’s registered observer list:

   1. Let options be registered’s options.

   2. If none of the following are true

      • node is not target and options["subtree"] is false
      • type is "attributes" and options["attributes"] either does not exist or is false
      • type is "attributes", options["attributeFilter"] exists, and options["attributeFilter"] does not contain name or namespace is non-null
      • type is "characterData" and options["characterData"] either does not exist or is false
      • type is "childList" and options["childList"] is false

      then:

      1. Let mo be registered’s observer.

      2. If interestedObservers[mo] does not exist, then set interestedObservers[mo] to null.

      3. If either type is "attributes" and options["attributeOldValue"] is true, or type is "characterData" and options["characterDataOldValue"] is true, then set interestedObservers[mo] to oldValue.

4. For each observer → mappedOldValue of interestedObservers:

   1. Let record be a new MutationRecord object with its type set to type, target set to target, attributeName set to name, attributeNamespace set to namespace, oldValue set to mappedOldValue, addedNodes set to addedNodes, removedNodes set to removedNodes, previousSibling set to previousSibling, and nextSibling set to nextSibling.

   2. Enqueue record to observer’s record queue.

   3. Append observer to the surrounding agent’s pending mutation observers.

5. Queue a mutation observer microtask.

To queue a tree mutation record for target with addedNodes, removedNodes, previousSibling, and nextSibling, run these steps:

1. Assert: either addedNodes or removedNodes is not empty.

2. Queue a mutation record of "childList" for target with null, null, null, addedNodes, removedNodes, previousSibling, and nextSibling.

4.3.3. Interface MutationRecord

[Exposed=Window]
interface MutationRecord {
  readonly attribute DOMString type;
  [SameObject] readonly attribute Node target;
  [SameObject] readonly attribute NodeList addedNodes;
  [SameObject] readonly attribute NodeList removedNodes;
  readonly attribute Node? previousSibling;
  readonly attribute Node? nextSibling;
  readonly attribute DOMString? attributeName;
  readonly attribute DOMString? attributeNamespace;
  readonly attribute DOMString? oldValue;
};

record . type

Returns "attributes" if it was an attribute mutation. "characterData" if it was a mutation to a CharacterData node. And "childList" if it was a mutation to the tree of nodes.

record . target

Returns the node the mutation affected, depending on the type. For "attributes", it is the element whose attribute changed. For "characterData", it is the CharacterData node. For "childList", it is the node whose children changed.

record . addedNodes

record . removedNodes

Return the nodes added and removed respectively.

record . previousSibling

record . nextSibling

Return the previous and next sibling respectively of the added or removed nodes; otherwise null.

record . attributeName

Returns the local name of the changed attribute; otherwise null.

record . attributeNamespace

Returns the namespace of the changed attribute; otherwise null.

record . oldValue

The return value depends on type. For "attributes", it is the value of the changed attribute before the change. For "characterData", it is the data of the changed node before the change. For "childList", it is null.

The type, target, addedNodes, removedNodes, previousSibling, nextSibling, attributeName, attributeNamespace, and oldValue attributes must return the values they were initialized to.

4.4. Interface Node

[Exposed=Window]
interface Node : EventTarget {
  const unsigned short ELEMENT_NODE = 1;
  const unsigned short ATTRIBUTE_NODE = 2;
  const unsigned short TEXT_NODE = 3;
  const unsigned short CDATA_SECTION_NODE = 4;
  const unsigned short ENTITY_REFERENCE_NODE = 5; // legacy
  const unsigned short ENTITY_NODE = 6; // legacy
  const unsigned short PROCESSING_INSTRUCTION_NODE = 7;
  const unsigned short COMMENT_NODE = 8;
  const unsigned short DOCUMENT_NODE = 9;
  const unsigned short DOCUMENT_TYPE_NODE = 10;
  const unsigned short DOCUMENT_FRAGMENT_NODE = 11;
  const unsigned short NOTATION_NODE = 12; // legacy
  readonly attribute unsigned short nodeType;
  readonly attribute DOMString nodeName;

  readonly attribute USVString baseURI;

  readonly attribute boolean isConnected;
  readonly attribute Document? ownerDocument;
  Node getRootNode(optional GetRootNodeOptions options = {});
  readonly attribute Node? parentNode;
  readonly attribute Element? parentElement;
  boolean hasChildNodes();
  [SameObject] readonly attribute NodeList childNodes;
  readonly attribute Node? firstChild;
  readonly attribute Node? lastChild;
  readonly attribute Node? previousSibling;
  readonly attribute Node? nextSibling;

  [CEReactions] attribute DOMString? nodeValue;
  [CEReactions] attribute DOMString? textContent;
  [CEReactions] undefined normalize();

  [CEReactions, NewObject] Node cloneNode(optional boolean deep = false);
  boolean isEqualNode(Node? otherNode);
  boolean isSameNode(Node? otherNode); // legacy alias of ===

  const unsigned short DOCUMENT_POSITION_DISCONNECTED = 0x01;
  const unsigned short DOCUMENT_POSITION_PRECEDING = 0x02;
  const unsigned short DOCUMENT_POSITION_FOLLOWING = 0x04;
  const unsigned short DOCUMENT_POSITION_CONTAINS = 0x08;
  const unsigned short DOCUMENT_POSITION_CONTAINED_BY = 0x10;
  const unsigned short DOCUMENT_POSITION_IMPLEMENTATION_SPECIFIC = 0x20;
  unsigned short compareDocumentPosition(Node other);
  boolean contains(Node? other);

  DOMString? lookupPrefix(DOMString? namespace);
  DOMString? lookupNamespaceURI(DOMString? prefix);
  boolean isDefaultNamespace(DOMString? namespace);

  [CEReactions] Node insertBefore(Node node, Node? child);
  [CEReactions] Node appendChild(Node node);
  [CEReactions] Node replaceChild(Node node, Node child);
  [CEReactions] Node removeChild(Node child);
};

dictionary GetRootNodeOptions {
  boolean composed = false;
};