DOM

Goals

This specification standardizes the DOM. It does so as follows:

1. By consolidating DOM Level 3 Core [DOM-Level-3-Core], Element Traversal [ELEMENTTRAVERSAL], Selectors API Level 2 [SELECTORS-API2], the "DOM Event Architecture" and "Basic Event Interfaces" chapters of DOM Level 3 Events [uievents-20031107] (specific types of events do not belong in the DOM Standard), and DOM Level 2 Traversal and Range [DOM-Level-2-Traversal-Range], and:

   • Aligning them with the JavaScript ecosystem where possible.
   • Aligning them with existing implementations.
   • Simplifying them as much as possible.

2. By moving features from the HTML Standard [HTML] that make more sense to be specified as part of the DOM Standard.

3. By defining a replacement for the "Mutation Events" and "Mutation Name Event Types" chapters of DOM Level 3 Events [uievents-20031107] as the old model was problematic.

   The old model is expected to be removed from implementations in due course.

4. By defining new features that simplify common DOM operations.

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]

The term context object means the object on which the algorithm, attribute getter, attribute setter, or method being discussed was called. When the context object is unambiguous, the term can be omitted.

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 the strings in set, separated from each other by U+0020, if set is non-empty, and the empty string otherwise.

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.

3. Return the result of evaluate a selector s against 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 if qualifiedName does not match the Name or QName production.

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

1. If namespace is the empty string, set it to null.
2. Validate qualifiedName.
3. Let prefix be null.
4. Let localName be qualifiedName.
5. If qualifiedName contains a ":" (U+003E), then split the string on it and set prefix to the part before and localName to the part after.
6. If prefix is non-null and namespace is null, then throw a NamespaceError.
7. If prefix is "xml" and namespace is not the XML namespace, then throw a NamespaceError.
8. If either qualifiedName or prefix is "xmlns" and namespace is not the XMLNS namespace, then throw a NamespaceError.
9. If namespace is the XMLNS namespace and neither qualifiedName nor prefix is "xmlns", then throw a NamespaceError.
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.

Events are objects too and implement the Event interface (or a derived interface). In the example above ev is the event. It is passed as argument to 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).

Now while typically events are dispatched by the user agent as the result of user interaction or the completion of some task, applications can dispatch events themselves, 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. First all object’s ancestor event listeners whose capture variable is set to true are invoked, in tree order. Second, object’s own event listeners are invoked. And finally, and only if event’s bubbles attribute value is true, object’s ancestor event listeners are invoked again, but now in reverse tree order.

Lets 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

[Constructor(DOMString type, optional EventInit eventInitDict),
 Exposed=(Window,Worker)]
interface Event {
  readonly attribute DOMString type;
  readonly attribute EventTarget? target;
  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;

  void stopPropagation();
           attribute boolean cancelBubble; // historical alias of .stopPropagation
  void stopImmediatePropagation();

  readonly attribute boolean bubbles;
  readonly attribute boolean cancelable;
  void preventDefault();
  readonly attribute boolean defaultPrevented;
  readonly attribute boolean composed;

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

  void initEvent(DOMString type, optional boolean bubbles = false, optional boolean cancelable = false); // historical
};

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.

An event has an associated relatedTarget (null or an EventTarget object). Unless stated otherwise it is null.

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

An event has an associated path. A path is a list of tuples, each of which consists of an item (an EventTarget object), target (null or an EventTarget object), and a relatedTarget (null or an EventTarget object). A tuple is formatted as (item, target, relatedTarget). A path is initially the empty list.

Specifications may define retargeting steps for all or some events. The algorithm is passed event, as indicated in the dispatch algorithm below.

event = new Event(type [, eventInitDict])

Returns a new event whose type attribute value is set to type. The optional 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.

event . currentTarget

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

event . composedPath()

Returns the item 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 attribute value’s ancestors in reverse tree order, and false otherwise.

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, and false otherwise.

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 attribute value, and false otherwise.

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 time origin.

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 and currentTarget attributes must return the values they were initialized to. When an event is created the attributes must be initialized to null.

The composedPath() method, when invoked, must run these steps:

1. Let composedPath be a new empty list.

2. Let currentTarget be context object’s currentTarget attribute value.

3. For each tuple in context object’s path:

   1. If currentTarget is a Window object, then:

      1. If tuple’s item is not a node, or tuple’s item is not closed-shadow-hidden from tuple’s item’s shadow-including root, then append tuple’s item to composedPath.

   2. Otherwise, if currentTarget is a node and tuple’s item is not closed-shadow-hidden from currentTarget, or currentTarget is not a node, then append tuple’s item to composedPath.

4. Return composedPath.

This algorithm assumes that when the target argument to the dispatch algorithm is not a node, none of the tuples in event argument’s eventual path will contain a node either.

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 attribute value.

AT_TARGET (numeric value 2)

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

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 attribute value.

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, when invoked, must set the context object’s stop propagation flag.

The cancelBubble attribute’s getter must return true if context object’s stop propagation flag is set, and false otherwise.

The cancelBubble attribute’s setter must set context object’s stop propagation flag if the given value is true, and do nothing otherwise.

The stopImmediatePropagation() method, when invoked, must set context object’s stop propagation flag and context object’s stop immediate propagation flag.

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

The preventDefault() method, when invoked, must set the canceled flag if the cancelable attribute value is true and the in passive listener flag is unset.

This means 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 attribute’s getter must return true if context object’s canceled flag is set, and false otherwise.

The composed attribute’s getter must return true if context object’s composed flag is set, and false otherwise.

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.

User agents are strongly encouraged to set minimum resolution of the timeStamp attribute to 5 microseconds following the existing clock resolution recommendation. [HR-TIME]

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

1. Set the initialized flag.
2. Unset the stop propagation flag, stop immediate propagation flag, and canceled flag.
3. Set the isTrusted attribute to false.
4. Set the target attribute to null.
5. Set the type attribute to type.
6. Set the bubbles attribute to bubbles.
7. Set the cancelable attribute to cancelable.

The initEvent(type, bubbles, cancelable) method, when invoked, must run these steps:

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

2. Initialize context object with type, bubbles, and cancelable.

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

2.3. Interface CustomEvent

[Constructor(DOMString type, optional CustomEventInit eventInitDict),
 Exposed=(Window,Worker)]
interface CustomEvent : Event {
  readonly attribute any detail;

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

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 optional 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 must, when invoked, run these steps:

1. If context object’s dispatch flag is set, then return.
2. Initialize the context object with type, bubbles, and cancelable.
3. Set context object’s detail attribute to detail.

2.4. Constructing events

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. Create a new object event using this interface.

2. Set event’s initialized flag.

3. Initialize event’s type attribute to type.

4. Initialize event’s timeStamp attribute to a DOMHighResTimeStamp representing the high resolution time from the time origin to the occurrence of the call to the event’s constructor.

5. For each dictionary member present in eventInitDict, find the attribute on event whose identifier matches the key of the dictionary member and then set the attribute to the value of that dictionary member.

6. 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. Create a new object event using eventInterface. If realm is given, 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 heycam/webidl#135.

2. Set event’s initialized flag.

3. Let defaultEventInitDict 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.)

4. For each dictionary member present in defaultEventInitDict, find the attribute on event whose identifier matches the key of the dictionary member and then set the attribute to the default value of that dictionary member.

5. Set event’s timeStamp attribute to a DOMHighResTimeStamp representing the high resolution time from the time origin to the occurrence that the event is signaling.

   For example, in macOS the occurrence time for input actions are available via the timestamp property of corresponding NSEvent objects. So in this case, the timeStamp value will be equivalent to the NSEvent’s timestamp offset by time origin, translated in milliseconds, and with its precision adjusted to meet the minimum clock resolution.

6. Initialize event’s isTrusted attribute to true.

7. 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.

2.5. 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.6. Interface EventTarget

[Constructor,
 Exposed=(Window,Worker)]
interface EventTarget {
  void addEventListener(DOMString type, EventListener? callback, optional (AddEventListenerOptions or boolean) options);
  void removeEventListener(DOMString type, EventListener? callback, optional (EventListenerOptions or boolean) options);
  boolean dispatchEvent(Event event);
};

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

dictionary EventListenerOptions {
  boolean capture = false;
};

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

The EventTarget object represents the target to which an event is dispatched when something has occurred.

Each EventTarget object has an associated list of event listeners.

An event listener can be used to observe a specific event.

An event listener consists of these fields:

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

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

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 just a boolean, in which case the method behaves exactly as if the value was specified as options’ capture member.

When set to true, options’ capture member 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’ passive member indicates that the callback will not cancel the event by invoking preventDefault(). This is used to enable performance optimizations described in §2.7 Observing event listeners.

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

The event listener is appended to target’s list of event listeners and is not appended if it is a duplicate, i.e., having the same type, callback, and capture values.

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

Remove the event listener in target’s list of event listeners 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, and false otherwise.

To flatten options, run these steps:

1. If options is a boolean, then return options.

2. Return options’s capture.

To flatten more options, run these steps:

1. Let capture be the result of flattening options.

2. Let once and passive be false.

3. If options is a dictionary, then set passive to options’s passive and once to options’s once.

4. Return capture, passive, and once.

The EventTarget() constructor, when invoked, must return a new EventTarget.

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.

The addEventListener(type, callback, options) method, when invoked, must run these steps:

1. If context object’s relevant global object is a ServiceWorkerGlobalScope object and its associated service worker’s script resource’s has ever been evaluated flag is set, then throw a TypeError. [SERVICE-WORKERS]

   To optimize storing the event types allowed for the service worker and to avoid non-deterministic changes to the event listeners, invocation of the method is allowed only during the very first evaluation of the service worker script.

2. If callback is null, then return.

3. Let capture, passive, and once be the result of flattening more options.

4. If context object’s associated list of event listener does not contain an event listener whose type is type, callback is callback, and capture is capture, then append a new event listener to it, whose type is type, callback is callback, capture is capture, passive is passive, and once is once.

The removeEventListener(type, callback, options) method, when invoked, must, run these steps

1. If context object’s relevant global object is a ServiceWorkerGlobalScope object and its associated service worker’s script resource’s has ever been evaluated flag is set, then throw a TypeError. [SERVICE-WORKERS]

2. Let capture be the result of flattening options.

3. If there is an event listener in the associated list of event listeners whose type is type, callback is callback, and capture is capture, then set that event listener’s removed to true and remove it from the associated list of event listeners.

The dispatchEvent(event) method, when invoked, must run these steps:

1. If event’s dispatch flag is set, or if its initialized flag is not set, then throw an InvalidStateError.

2. Initialize event’s isTrusted attribute to false.

3. Return the result of dispatching event to context object.

2.7. 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 public-script-coord@w3.org for discussion).

2.8. 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 relatedTarget be the result of retargeting event’s relatedTarget against target if event’s relatedTarget is non-null, and null otherwise.

4. If target is relatedTarget and target is not event’s relatedTarget, then return true.

5. Append (target, targetOverride, relatedTarget) to event’s path.

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

7. Let activationTarget be target, if isActivationEvent is true and target has activation behavior, and null otherwise.

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

9. While parent is non-null:

   1. Let relatedTarget be the result of retargeting event’s relatedTarget against parent if event’s relatedTarget is non-null, and null otherwise.

   2. If 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 (parent, null, relatedTarget) to event’s path.

   3. Otherwise, if parent and relatedTarget are identical, then set parent to null.

   4. 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 (parent, target, relatedTarget) to event’s path.

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

10. Set event’s eventPhase attribute to CAPTURING_PHASE.

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

12. For each tuple in event’s path, in reverse order:

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

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

    3. Run the retargeting steps with event.

    4. If tuple’s target is null, then invoke tuple’s item with event and legacyOutputDidListenersThrowFlag if given.

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

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

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

    3. Run the retargeting steps with event.

    4. If tuple’s target is non-null, then set event’s eventPhase attribute to AT_TARGET.

    5. Otherwise, set event’s eventPhase attribute to BUBBLING_PHASE.

    6. If either event’s eventPhase attribute is BUBBLING_PHASE and event’s bubbles attribute is true or event’s eventPhase attribute is AT_TARGET, then invoke tuple’s item with event and legacyOutputDidListenersThrowFlag if given.

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

15. Set event’s eventPhase attribute to NONE.

16. Set event’s currentTarget attribute to null.

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

18. 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.

19. Return false if event’s canceled flag is set, and true otherwise.

To invoke an object with event and an optional legacyOutputDidListenersThrowFlag, run these steps:

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

2. Let listeners be a new list.

3. For each event listener associated with object, append a pointer to the event listener to listeners.

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

4. Initialize event’s currentTarget attribute to object.

5. Let found be the result of running inner invoke object with event, listeners, and legacyOutputDidListenersThrowFlag if given.

6. 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 object with event, listeners, and legacyOutputDidListenersThrowFlag if given.

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

To inner invoke an object with event, listeners, 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 event’s eventPhase attribute value is CAPTURING_PHASE and listener’s capture is false, then continue.

   4. If event’s eventPhase attribute value is BUBBLING_PHASE and listener’s capture is true, then continue.

   5. If listener’s once is true, then remove listener from object’s associated list of event listeners.

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

   7. Call a user object’s operation with listener’s callback, "handleEvent", a list of arguments consisting of event, and event’s currentTarget attribute value as the callback this 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]

   8. Unset event’s in passive listener flag.

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

3. Return found.

2.9. 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.10. 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 a new DOMException with error name "AbortError".

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) => {
    // Begin doing amazingness, and call resolve(result) when done.
    // But also, watch for signals:
    signal.addEventListener('abort', () => {
      // Stop doing amazingness, and:
      reject(new DOMException('Aborted', 'AbortError'));
    });
  });
}

3.1. Interface AbortController

[Constructor,
 Exposed=(Window,Worker)]
interface AbortController {
  [SameObject] readonly attribute AbortSignal signal;

  void abort();
};

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()

Invoking this method will set this object’s AbortSignal's aborted flag and signal to any observers that the associated activity is to be aborted.

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

The AbortController() constructor, when invoked, must run these steps:

1. Let signal be a new AbortSignal object.

2. Let controller be a new AbortController object whose signal is signal.

3. Return controller.

The signal attribute’s getter must return context object’s signal.

The abort() method, when invoked, must signal abort on context object’s signal.

3.2. Interface AbortSignal

[Exposed=(Window,Worker)]
interface AbortSignal : EventTarget {
  readonly attribute boolean aborted;

  attribute EventHandler onabort;
};

signal . aborted

Returns true if this AbortSignal's AbortController has signaled to abort, and false otherwise.

An AbortSignal object has an associated aborted flag. It is unset unless specified otherwise.

An AbortSignal object has associated abort algorithms, which is a set of algorithms which are to be executed when its aborted flag is set. Unless specified otherwise, its value is the empty set.

To add an algorithm algorithm to an AbortSignal object signal, run these steps:

1. If signal’s aborted flag is set, then return.

2. Append algorithm to signal’s abort algorithms.

To remove an algorithm algorithm from an AbortSignal signal, remove algorithm from signal’s abort algorithms.

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

The aborted attribute’s getter must return true if context object’s aborted flag is set, and false otherwise.

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

To signal abort, given a AbortSignal object signal, run these steps:

1. If signal’s aborted flag is set, then return.

2. Set signal’s aborted flag.

3. For each algorithm in signal’s abort algorithms: run algorithm.

4. Empty signal’s abort algorithms.

5. Fire an event named abort at signal.

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 an "AbortError" DOMException.
• Reject immediately if the AbortSignal's aborted flag is already set, 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

Document, DocumentType, DocumentFragment, Element, Text, ProcessingInstruction, and Comment objects (simply called nodes) participate in a tree, simply named the node tree.

A node tree is constrained as follows, expressed as a relationship between the type of node and its allowed children:

Document

In tree order:

1. Zero or more nodes each of which is ProcessingInstruction or Comment.

2. Optionally one DocumentType node.

3. Zero or more nodes each of which is ProcessingInstruction or Comment.

4. Optionally one Element node.

5. Zero or more nodes each of which is ProcessingInstruction or Comment.

DocumentFragment

Element

Zero or more nodes each of which is Element, Text, ProcessingInstruction, or Comment.

DocumentType

Text

ProcessingInstruction

Comment

None.

To determine the length of a node node, switch on node:

DocumentType

Zero.

Text

ProcessingInstruction

Comment

The number of code units in its data.

Any other node

Its number of children.

A node is considered empty if its length is zero.

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, and null otherwise.

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 slotables for a tree with element’s tree.

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 slotables). Unless stated otherwise it is empty.

4.2.2.2. Slotables

Element and Text nodes are slotables.

A slot can be a slotable.

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

Use these attribute change steps to update a slotable’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 slotables for element’s assigned slot.

   7. Run assign a slot for element.

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

4.2.2.3. Finding slots and slotables

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

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

2. Let shadow be slotable’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. Return the first slot in shadow’s tree whose name is slotable’s name, if any, and null otherwise.

To find slotables 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 host be slot’s root’s host.

4. For each slotable child of host, slotable, in tree order:

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

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

5. Return result.

To find flattened slotables 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 slotables be the result of finding slotables given slot.

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

5. For each node in slotables:

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

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

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

   2. Otherwise, append node to result.

6. Return result.

4.2.2.4. Assigning slotables and slots

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

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

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

3. Set slot’s assigned nodes to slotables.

4. For each slotable in slotables, set slotable’s assigned slot to slot.

To assign slotables for a tree, given a tree tree, run assign slotables for each slot slot in tree, in tree order.

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

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

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

4.2.2.5. Signaling slot change

Each unit of related similar-origin browsing contexts has a signal slot list (a list of slots). Unless stated otherwise it is empty. [HTML]

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

1. If slot is not in unit of related similar-origin browsing contexts' signal slot list, append slot to unit of related similar-origin browsing contexts' signal slot list.

2. Queue a mutation observer compound 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, throw a HierarchyRequestError.
2. If node is a host-including inclusive ancestor of parent, throw a HierarchyRequestError.
3. If child is not null and its parent is not parent, then throw a NotFoundError.
4. If node is not a DocumentFragment, DocumentType, Element, Text, ProcessingInstruction, or Comment node, throw a HierarchyRequestError.
5. If either node is a Text node and parent is a document, or node is a doctype and parent is not a document, throw a HierarchyRequestError.
6. If parent is a document, and any of the statements below, switched on node, are true, throw a HierarchyRequestError.

   DocumentFragment node

   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 not null and a doctype is following child.

   element

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

   doctype

   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 reference child be child.
3. If reference child is node, set it to node’s next sibling.
4. Adopt node into parent’s node document.
5. Insert node into parent before reference child.
6. Return node.

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

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

1. Let count be the number of children of node if it is a DocumentFragment node, and one otherwise.

2. If child is non-null, then:

   1. For each range whose start node is parent and start offset is greater than child’s index, increase its start offset by count.
   2. For each range whose end node is parent and end offset is greater than child’s index, increase its end offset by count.
3. Let nodes be node’s children if node is a DocumentFragment node, and a list containing solely node otherwise.
4. If node is a DocumentFragment node, remove its children with the suppress observers flag set.
5. If node is a DocumentFragment node, queue a mutation record of "childList" for node with removedNodes nodes.

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

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. If child is null, then append node to parent’s children.

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

   3. If parent is a shadow host and node is a slotable, then assign a slot for node.

   4. If node is a Text node, run the child text content change steps for parent.

   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 slotables for a tree with node’s tree.

   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, queue a mutation record of "childList" for parent with addedNodes nodes, nextSibling child, and previousSibling previousSibling.

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, throw a HierarchyRequestError.
2. If node is a host-including inclusive ancestor of parent, throw a HierarchyRequestError.
3. If child’s parent is not parent, then throw a NotFoundError.
4. If node is not a DocumentFragment, DocumentType, Element, Text, ProcessingInstruction, or Comment node, throw a HierarchyRequestError.
5. If either node is a Text node and parent is a document, or node is a doctype and parent is not a document, throw a HierarchyRequestError.
6. If parent is a document, and any of the statements below, switched on node, are true, throw a HierarchyRequestError.

   DocumentFragment node

   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.

   doctype

   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 reference child be child’s next sibling.
8. If reference child is node, set it to node’s next sibling.

9. Let previousSibling be child’s previous sibling.

10. Adopt node into parent’s node document.
11. Let removedNodes be the empty list.

12. If child’s parent is not null, then:

    1. Set removedNodes to a list solely containing child.

    2. Remove child from its parent with the suppress observers flag set.

    The above can only be false if child is node.

13. Let nodes be node’s children if node is a DocumentFragment node, and a list containing solely node otherwise.
14. Insert node into parent before reference child with the suppress observers flag set.
15. Queue a mutation record of "childList" for target parent with addedNodes nodes, removedNodes removedNodes, nextSibling reference child, and previousSibling previousSibling.
16. Return child.

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

1. If node is not null, adopt node into parent’s node document.
2. Let removedNodes be parent’s children.
3. Let addedNodes be the empty list if node is null, node’s children if node is a DocumentFragment node, and a list containing node otherwise.
4. Remove all parent’s children, in tree order, with the suppress observers flag set.
5. If node is not null, insert node into parent before null with the suppress observers flag set.
6. Queue a mutation record of "childList" for parent with addedNodes addedNodes and removedNodes removedNodes.

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.
2. Remove child from parent.
3. Return child.

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

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

1. Let index be node’s index.
2. For each range whose start node is an inclusive descendant of node, set its start to (parent, index).
3. For each range whose end node is an inclusive descendant of node, set its end to (parent, index).
4. For each range whose start node is parent and start offset is greater than index, decrease its start offset by one.
5. For each range whose end node is parent and end offset is greater than index, decrease its end offset by one.

6. 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.

7. Let oldPreviousSibling be node’s previous sibling.
8. Let oldNextSibling be node’s next sibling.
9. Remove node from its parent’s children.

10. If node is assigned, then run assign slotables for node’s assigned slot.

11. 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.

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

    1. Run assign slotables for a tree with parent’s tree.

    2. Run assign slotables for a tree with node’s tree.

13. Run the removing steps with node and parent.

14. If node is custom, 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.

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

    1. Run the removing steps with descendant.

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

16. For each inclusive ancestor inclusiveAncestor of parent, if inclusiveAncestor has any registered observers whose options' subtree is true, then for each such registered observer registered, append a transient registered observer whose observer and options are identical to those of registered and source which is registered to node’s list of registered observers.
17. If suppress observers flag is unset, queue a mutation record of "childList" for parent with removedNodes a list solely containing node, nextSibling oldNextSibling, and previousSibling oldPreviousSibling.
18. If node is a Text node, run the child text content change steps for parent.

4.2.4. Mixin NonElementParentNode

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

[NoInterfaceObject,
 Exposed=Window]
interface NonElementParentNode {
  Element? getElementById(DOMString elementId);
};
Document implements NonElementParentNode;
DocumentFragment implements NonElementParentNode;

node . getElementById(elementId)

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

The getElementById(elementId) method, when invoked, must return the first element, in tree order, within context object’s descendants, whose ID is elementId, and null if there is no such element otherwise.

4.2.5. Mixin DocumentOrShadowRoot

[NoInterfaceObject,
 Exposed=Window]
interface DocumentOrShadowRoot {
};
Document implements DocumentOrShadowRoot;
ShadowRoot implements 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, set node to that node.

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

5. Return node.

[NoInterfaceObject,
 Exposed=Window]
interface ParentNode {
  [SameObject] readonly attribute HTMLCollection children;
  readonly attribute Element? firstElementChild;
  readonly attribute Element? lastElementChild;
  readonly attribute unsigned long childElementCount;

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

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

collection = node . children

Returns the child elements.

element = node . firstElementChild

Returns the first child that is an element, and null otherwise.

element = node . lastElementChild

Returns the last child that is an element, and null otherwise.

node . prepend(nodes)

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

Throws a HierarchyRequestError 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 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 attribute’s getter must return an HTMLCollection collection rooted at context object matching only element children.

The firstElementChild attribute’s getter must return the first child that is an element, and null otherwise.

The lastElementChild attribute’s getter must return the last child that is an element, and null otherwise.

The childElementCount attribute’s getter must return the number of children of context object that are elements.

The prepend(nodes) method, when invoked, must run these steps:

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

2. Pre-insert node into context object before the context object’s first child.

The append(nodes) method, when invoked, must run these steps:

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

2. Append node to context object.

The querySelector(selectors) method, when invoked, must return the first result of running scope-match a selectors string selectors against context object, if the result is not an empty list, and null otherwise.

The querySelectorAll(selectors) method, when invoked, must return the static result of running scope-match a selectors string selectors against context object.

4.2.7. Mixin NonDocumentTypeChildNode

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

[NoInterfaceObject,
 Exposed=Window]
interface NonDocumentTypeChildNode {
  readonly attribute Element? previousElementSibling;
  readonly attribute Element? nextElementSibling;
};
Element implements NonDocumentTypeChildNode;
CharacterData implements NonDocumentTypeChildNode;

element = node . previousElementSibling

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

element = node . nextElementSibling

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

The previousElementSibling attribute’s getter must return the first preceding sibling that is an element, and null otherwise.

The nextElementSibling attribute’s getter must return the first following sibling that is an element, and null otherwise.

4.2.8. Mixin ChildNode

[NoInterfaceObject,
 Exposed=Window]
interface ChildNode {
  [CEReactions, Unscopable] void before((Node or DOMString)... nodes);
  [CEReactions, Unscopable] void after((Node or DOMString)... nodes);
  [CEReactions, Unscopable] void replaceWith((Node or DOMString)... nodes);
  [CEReactions, Unscopable] void remove();
};
DocumentType implements ChildNode;
Element implements ChildNode;
CharacterData implements ChildNode;

node . before(...nodes)

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

Throws a HierarchyRequestError 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 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 if the constraints of the node tree are violated.

node . remove()

Removes node.

The before(nodes) method, when invoked, must run these steps:

1. Let parent be context object’s parent.

2. If parent is null, then return.

3. Let viablePreviousSibling be context object’s first preceding sibling not in nodes, and null otherwise.

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

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

6. Pre-insert node into parent before viablePreviousSibling.

The after(nodes) method, when invoked, must run these steps:

1. Let parent be context object’s parent.

2. If parent is null, then return.

3. Let viableNextSibling be context object’s first following sibling not in nodes, and null otherwise.

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

5. Pre-insert node into parent before viableNextSibling.

The replaceWith(nodes) method, when invoked, must run these steps:

1. Let parent be context object’s parent.

2. If parent is null, then return.

3. Let viableNextSibling be context object’s first following sibling not in nodes, and null otherwise.

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

5. If context object’s parent is parent, replace the context object with node within parent.

   Context object could have been inserted into node.

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

The remove() method, when invoked, must run these steps:

1. If context object’s parent is null, then return.

2. Remove the context object from context object’s parent.

4.2.9. Mixin Slotable

[NoInterfaceObject,
 Exposed=Window]
interface Slotable {
  readonly attribute HTMLSlotElement? assignedSlot;
};
Element implements Slotable;
Text implements Slotable;

The assignedSlot attribute’s getter must return the result of find a slot given context object 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 an 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 attribute’s getter must return the number of nodes represented by the collection.

The item(index) method, when invoked, must 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, when invoked, must run these steps:

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 unit of related similar-origin browsing contexts has a mutation observer compound microtask queued flag, which is initially unset, and an associated list of MutationObserver objects, which is initially empty. [HTML]

To queue a mutation observer compound microtask, run these steps:

1. If mutation observer compound microtask queued flag is set, then return.
2. Set mutation observer compound microtask queued flag.
3. Queue a compound microtask to notify mutation observers.

To notify mutation observers, run these steps:

1. Unset mutation observer compound microtask queued flag.
2. Let notify list be a copy of unit of related similar-origin browsing contexts' list of MutationObserver objects.

3. Let signalList be a copy of unit of related similar-origin browsing contexts' signal slot list.

4. Empty unit of related similar-origin browsing contexts' signal slot list.

5. For each MutationObserver object mo in notify list, execute a compound microtask subtask to run these steps: [HTML]
   1. Let queue be a copy of mo’s record queue.
   2. Empty mo’s record queue.
   3. Remove all transient registered observers whose observer is mo.
   4. If queue is non-empty, invoke mo’s callback with a list of arguments consisting of queue and mo, and mo as the callback this value. If this throws an exception, report the exception.

6. For each slot slot in signalList, in order, fire an event named slotchange, with its bubbles attribute set to true, at slot.

Each node has an associated list of registered observers.

A registered observer consists of an observer (a MutationObserver object) and options (a MutationObserverInit dictionary). A transient registered observer is a specific type of registered observer that has a source which is 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

[Constructor(MutationCallback callback),
 Exposed=Window]
interface MutationObserver {
  void observe(Node target, optional MutationObserverInit options);
  void disconnect();
  sequence<MutationRecord> takeRecords();
};

callback MutationCallback = void (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 list of nodes on which it is a registered observer’s observer that is initially empty.
• A list of MutationRecord objects called the record queue that 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 and/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 MutationObserver(callback) constructor, when invoked, must create a new MutationObserver object with callback set to callback, append it to the unit of related similar-origin browsing contexts' list of MutationObserver objects, and then return it.

The observe(target, options) method, when invoked, must run these steps:

1. If either options’ attributeOldValue or attributeFilter is present and options’ attributes is omitted, set options’ attributes to true.
2. If options’ characterDataOldValue is present and options’ characterData is omitted, set options’ characterData to true.
3. If none of options’ childList, attributes, and characterData is true, throw a TypeError.
4. If options’ attributeOldValue is true and options’ attributes is false, throw a TypeError.
5. If options’ attributeFilter is present and options’ attributes is false, throw a TypeError.
6. If options’ characterDataOldValue is true and options’ characterData is false, throw a TypeError.
7. For each registered observer registered in target’s list of registered observers whose observer is the context object:
   1. Remove all transient registered observers whose source is registered.
   2. Replace registered’s options with options.
8. Otherwise, add a new registered observer to target’s list of registered observers with the context object as the observer and options as the options, and add target to context object’s list of nodes on which it is registered.

The disconnect() method, when invoked, must for each node node in context object’s list of nodes, remove any registered observer on node for which context object is the observer, and also empty context object’s record queue.

The takeRecords() method, when invoked, must return a copy of the record queue and then empty the record queue.

4.3.2. Queuing a mutation record

To queue a mutation record of type for target with one or more of (depends on type) name name, namespace namespace, oldValue oldValue, addedNodes addedNodes, removedNodes removedNodes, previousSibling previousSibling, and nextSibling nextSibling, run these steps:

1. Let interested observers be an initially empty set of MutationObserver objects optionally paired with a string.
2. Let nodes be the inclusive ancestors of target.

3. For each node in nodes, and then for each registered observer (with registered observer’s options as options) in node’s list of registered observers:

   1. If none of the following are true

      • node is not target and options’ subtree is false
      • type is "attributes" and options’ attributes is not true
      • type is "attributes", options’ attributeFilter is present, and options’ attributeFilter does not contain name or namespace is non-null
      • type is "characterData" and options’ characterData is not true
      • type is "childList" and options’ childList is false

      then:

      1. If registered observer’s observer is not in interested observers, append registered observer’s observer to interested observers.

      2. If either type is "attributes" and options’ attributeOldValue is true, or type is "characterData" and options’ characterDataOldValue is true, set the paired string of registered observer’s observer in interested observers to oldValue.

4. For each observer in interested observers:

   1. Let record be a new MutationRecord object with its type set to type and target set to target.
   2. If name and namespace are given, set record’s attributeName to name, and record’s attributeNamespace to namespace.
   3. If addedNodes is given, set record’s addedNodes to addedNodes.
   4. If removedNodes is given, set record’s removedNodes to removedNodes,
   5. If previousSibling is given, set record’s previousSibling to previousSibling.
   6. If nextSibling is given, set record’s nextSibling to nextSibling.
   7. If observer has a paired string, set record’s oldValue to observer’s paired string.
   8. Append record to observer’s record queue.
5. Queue a mutation observer compound microtask.

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, and null otherwise.

record . attributeName

Returns the local name of the changed attribute, and null otherwise.

record . attributeNamespace

Returns the namespace of the changed attribute, and null otherwise.

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 and target attributes must return the values they were initialized to.

The addedNodes and removedNodes attributes must return the values they were initialized to. Unless stated otherwise, when a MutationRecord object is created, they must both be initialized to an empty NodeList.

The previousSibling, nextSibling, attributeName, attributeNamespace, and oldValue attributes must return the values they were initialized to. Unless stated otherwise, when a MutationRecord object is created, they must be initialized to null.

4.3.4. Garbage collection

Nodes have a strong reference to registered observers in their list of registered observers.

Registered observers in a node’s list of registered observers have a weak reference to the node.

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; // historical
  const unsigned short ENTITY_NODE = 6; // historical
  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; // historical
  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] void normalize();

  [CEReactions, NewObject] Node cloneNode(optional boolean deep = false);
  boolean isEqualNode(Node? otherNode);
  boolean isSameNode(Node? otherNode); // historical 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;
};

Node is an abstract interface and does not exist as node. It is used by all nodes (Document, DocumentType, DocumentFragment, Element, Text, ProcessingInstruction, and Comment).

Each node has an associated node document, set upon creation, that is a document.

A node’s node document can be changed by the adopt algorithm.

A node’s get the parent algorithm, given an event, returns the node’s assigned slot, if node is assigned, and node’s parent otherwise.

node . nodeType

Returns the type of node, represented by a number from the following list:

Node . ELEMENT_NODE (1)

node is an element.

Node . TEXT_NODE (3)

node is a Text node.

Node . CDATA_SECTION_NODE (4)

node is a CDATASection node.

Node . PROCESSING_INSTRUCTION_NODE (7)

node is a ProcessingInstruction node.

Node . COMMENT_NODE (8)

node is a Comment node.

Node . DOCUMENT_NODE (9)

node is a document.

Node . DOCUMENT_TYPE_NODE (10)

node is a doctype.

Node . DOCUMENT_FRAGMENT_NODE (11)

node is a DocumentFragment node.

node . nodeName

Returns a string appropriate for the type of node, as follows:

Element

Its tagName attribute value.

Attr

Its qualified name.

Text

"#text".

CDATASection

"#cdata-section".

ProcessingInstruction

Its target.

Comment

"#comment".

Document

"#document".

DocumentType

Its name.

DocumentFragment

"#document-fragment".

The nodeType attribute’s getter, when invoked, must return the first matching statement, switching on the context object:

Element

ELEMENT_NODE (1)

Attr

ATTRIBUTE_NODE (2);

Text

TEXT_NODE (3);

CDATASection

CDATA_SECTION_NODE (4);

ProcessingInstruction

PROCESSING_INSTRUCTION_NODE (7);

Comment

COMMENT_NODE (8);

Document

DOCUMENT_NODE (9);

DocumentType

DOCUMENT_TYPE_NODE (10);

DocumentFragment

DOCUMENT_FRAGMENT_NODE (11).

The nodeName attribute’s getter, when invoked, must return the first matching statement, switching on the context object:

Element

Its tagName attribute value.

Attr

Its qualified name.

Text

"#text".

CDATASection

"#cdata-section".

ProcessingInstruction

Its target.

Comment

"#comment".

Document

"#document".

DocumentType

Its name.

DocumentFragment

"#document-fragment".

node . baseURI

Returns node’s node document’s document base URL.

The baseURI attribute’s getter must return node document’s document base URL, serialized.

node . isConnected

Returns true if node is connected and false otherwise.

node . ownerDocument

Returns the node document. Returns null for documents.

node . getRootNode()

Returns node’s root.

node . getRootNode({ composed:true })

Returns node’s shadow-including root.

node . parentNode

Returns the parent.

node . parentElement

Returns the parent element.

node . hasChildNodes()

Returns whether node has children.

node . childNodes

Returns the children.

node . firstChild

Returns the first child.

node . lastChild

Returns the last child.

node . previousSibling

Returns the previous sibling.

node . nextSibling

Returns the next sibling.

The isConnected attribute’s getter must return true, if context object is connected, and false otherwise.

The ownerDocument attribute’s getter must return null, if the context object is a document, and the context object’s node document otherwise.

The node document of a document is that document itself. All nodes have a node document at all times.

The getRootNode(options) method, when invoked, must return context object’s shadow-including root if options’s composed is true, and context object’s root otherwise.

The parentNode attribute’s getter must return the context object’s parent.

An Attr node has no parent.

The parentElement attribute’s getter must return the context object’s parent element.

The hasChildNodes() method, when invoked, must return true if the context object has children, and false otherwise.

The childNodes attribute’s getter must return a NodeList rooted at the context object matching only children.

The firstChild attribute’s getter must return the context object’s first child.

The lastChild attribute’s getter must return the context object’s last child.

The previousSibling attribute’s getter must return the context object’s previous sibling.

An Attr node has no siblings.

The nextSibling attribute’s getter must return the context object’s next sibling.

The nodeValue attribute must return the following, depending on the context object:

Attr

Context object’s value.

Text

ProcessingInstruction

Comment

Context object’s data.

Any other node

Null.

The nodeValue attribute must, on setting, if the new value is null, act as if it was the empty string instead, and then do as described below, depending on the context object:

Attr

Set an existing attribute value with context object and new value.

Text

ProcessingInstruction

Comment

Replace data with node context object, offset 0, count context object’s length, and data new value.

Any other node

Do nothing.

The textContent attribute’s getter must return the following, switching on context object:

DocumentFragment

Element

The concatenation of data of all the Text node descendants of the context object, in tree order.

Attr

Context object’s value.

Text

ProcessingInstruction

Comment

Context object’s data.

Any other node

Null.

The textContent attribute’s setter must, if the given value is null, act as if it was the empty string instead, and then do as described below, switching on context object:

DocumentFragment

Element

1. Let node be null.

2. If the given value is not the empty string, set node to a new Text node whose data is the given value and node document is context object’s node document.

3. Replace all with node within the context object.

Attr

Set an existing attribute value with context object and new value.

Text

ProcessingInstruction

Comment

Replace data with node context object, offset 0, count context object’s length, and data the given value.

Any other node

Do nothing.

node . normalize()

Removes empty exclusive Text nodes and concatenates the data of remaining contiguous exclusive Text nodes into the first of their nodes.

The normalize() method, when invoked, must run these steps for each descendant exclusive Text node node of context object:

1. Let length be node’s length.
2. If length is zero, then remove node and continue with the next exclusive Text node, if any.
3. Let data be the concatenation of the data of node’s contiguous exclusive Text nodes (excluding itself), in tree order.
4. Replace data with node node, offset length, count 0, and data data.
5. Let currentNode be node’s next sibling.

6. While currentNode is an exclusive Text node:

   1. For each range whose start node is currentNode, add length to its start offset and set its start node to node.

   2. For each range whose end node is currentNode, add length to its end offset and set its end node to node.

   3. For each range whose start node is currentNode’s parent and start offset is currentNode’s index, set its start node to node and its start offset to length.

   4. For each range whose end node is currentNode’s parent and end offset is currentNode’s index, set its end node to node and its end offset to length.

   5. Add currentNode’s length to length.

   6. Set currentNode to its next sibling.

7. Remove node’s contiguous exclusive Text nodes (excluding itself), in tree order.

normalize() does not need to run any child text content change steps, since although it messes with Text nodes extensively, it does so specifically in a way that preserves the child text content.

node . cloneNode([deep = false])

Returns a copy of node. If deep is true, the copy also includes the node’s descendants.

node . isEqualNode(otherNode)

Returns whether node and otherNode have the same properties.

node . compareDocumentPosition(other)

Returns a bitmask indicating the position of other relative to node. These are the bits that can be set:

Node . DOCUMENT_POSITION_DISCONNECTED (1)

Set when node and other are not in the same tree.

Node . DOCUMENT_POSITION_PRECEDING (2)

Set when other is preceding node.

Node . DOCUMENT_POSITION_FOLLOWING (4)

Set when other is following node.

Node . DOCUMENT_POSITION_CONTAINS (8)

Set when other is an ancestor of node.

Node . DOCUMENT_POSITION_CONTAINED_BY (16, 10 in hexadecimal)

Set when other is a descendant of node.

node . contains(other)

Returns true if other is an inclusive descendant of node, and false otherwise.

These are the constants compareDocumentPosition() returns as mask:

• DOCUMENT_POSITION_DISCONNECTED (1);
• DOCUMENT_POSITION_PRECEDING (2);
• DOCUMENT_POSITION_FOLLOWING (4);
• DOCUMENT_POSITION_CONTAINS (8);
• DOCUMENT_POSITION_CONTAINED_BY (16, 10 in hexadecimal);
• DOCUMENT_POSITION_IMPLEMENTATION_SPECIFIC (32, 20 in hexadecimal).

The compareDocumentPosition(other) method, when invoked, must run these steps:

1. If context object is other, then return zero.

2. Let node1 be other and node2 be context object.

3. Let attr1 and attr2 be null.

4. If node1 is an attribute, then set attr1 to node1 and node1 to attr1’s element.

5. If node2 is an attribute, then:

   1. Set attr2 to node2 and node2 to attr2’s element.

   2. If attr1 and node1 are non-null, and node2 is node1, then:

      1. For each attr in node2’s attribute list:

         1. If attr equals attr1, then return the result of adding DOCUMENT_POSITION_IMPLEMENTATION_SPECIFIC and DOCUMENT_POSITION_PRECEDING.

         2. If attr equals attr2, then return the result of adding DOCUMENT_POSITION_IMPLEMENTATION_SPECIFIC and DOCUMENT_POSITION_FOLLOWING.

6. If node1 or node2 is null, or node1’s root is not node2’s root, then return the result of adding DOCUMENT_POSITION_DISCONNECTED, DOCUMENT_POSITION_IMPLEMENTATION_SPECIFIC, and either DOCUMENT_POSITION_PRECEDING or DOCUMENT_POSITION_FOLLOWING, with the constraint that this is to be consistent, together.

   Whether to return DOCUMENT_POSITION_PRECEDING or DOCUMENT_POSITION_FOLLOWING is typically implemented via pointer comparison. In JavaScript implementations a cached Math.random() value can be used.

7. If node1 is an ancestor of node2 and attr1 is null, or node1 is node2 and attr2 is non-null, then return the result of adding DOCUMENT_POSITION_CONTAINS to DOCUMENT_POSITION_PRECEDING.

8. If node1 is a descendant of node2 and attr2 is null, or node1 is node2 and attr1 is non-null, then return the result of adding DOCUMENT_POSITION_CONTAINED_BY to DOCUMENT_POSITION_FOLLOWING.

9. If node1 is preceding node2, then return DOCUMENT_POSITION_PRECEDING.

   Due to the way attributes are handled in this algorithm this results in a node’s attributes counting as preceding that node’s children, despite attributes not participating in a tree.

10. Return DOCUMENT_POSITION_FOLLOWING.

The contains(other) method, when invoked, must return true if other is an inclusive descendant of context object, and false otherwise (including when other is null).

To locate a namespace prefix for an element using namespace, run these steps:

1. If element’s namespace is namespace and its namespace prefix is not null, then return its namespace prefix.

2. If element has an attribute whose namespace prefix is "xmlns" and value is namespace, then return element’s first such attribute’s local name.

3. If element’s parent element is not null, then return the result of running locate a namespace prefix on that element using namespace.

4. Return null.

To locate a namespace for a node using prefix, switch on node:

Element

1. If its namespace is not null and its namespace prefix is prefix, then return namespace.

2. If it has an attribute whose namespace is the XMLNS namespace, namespace prefix is "xmlns", and local name is prefix, or if prefix is null and it has an attribute whose namespace is the XMLNS namespace, namespace prefix is null, and local name is "xmlns", then return its value if it is not the empty string, and null otherwise.

3. If its parent element is null, then return null.

4. Return the result of running locate a namespace on its parent element using prefix.

Document

1. If its document element is null, then return null.

2. Return the result of running locate a namespace on its document element using prefix.

DocumentType

DocumentFragment

Return null.

Attr

1. If its element is null, then return null.

2. Return the result of running locate a namespace on its element using prefix.

Any other node

1. If its parent element is null, then return null.

2. Return the result of running locate a namespace on its parent element using prefix.

The lookupPrefix(namespace) method, when invoked, must run these steps:

1. If namespace is null or the empty string, then return null.

2. Switch on the context object:

   Element

   Return the result of locating a namespace prefix for it using namespace.

   Document

   Return the result of locating a namespace prefix for its document element, if its document element is non-null, and null otherwise.

   DocumentType

   DocumentFragment

   Return null.

   Attr

   Return the result of locating a namespace prefix for its element, if its element is non-null, and null otherwise.

   Any other node

   Return the result of locating a namespace prefix for its parent element, if its parent element is non-null, and null otherwise.