DOM Standard

1. Infrastructure

This specification depends on the Infra Standard. [INFRA]

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

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

1.1. Trees

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

1.2. Ordered sets

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

Let inputTokens be the result of splitting input on ASCII whitespace.
Let tokens be a new ordered set.
For each token in inputTokens, append token to tokens.
Return tokens.

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

1.3. Selectors

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

Let s be the result of parse a selector selectors. [SELECTORS4]
If s is failure, then throw a "SyntaxError" DOMException.
Return the result of match a selector against a tree with s and node’s root using scoping root node. [SELECTORS4].

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

1.4. Namespaces

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

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

If namespace is the empty string, then set it to null.
Validate qualifiedName.
Let prefix be null.
Let localName be qualifiedName.
If qualifiedName contains a U+003A (:), then:
1. Let splitResult be the result of running strictly split given qualifiedName and U+003A (:).
2. Set prefix to splitResult[0].
3. Set localName to splitResult[1].
If prefix is non-null and namespace is null, then throw a "NamespaceError" DOMException.
If prefix is "xml" and namespace is not the XML namespace, then throw a "NamespaceError" DOMException.
If either qualifiedName or prefix is "xmlns" and namespace is not the XMLNS namespace, then throw a "NamespaceError" DOMException.
If namespace is the XMLNS namespace and neither qualifiedName nor prefix is "xmlns", then throw a "NamespaceError" DOMException.
Return namespace, prefix, and localName.

2. Events

2.1. Introduction to "DOM Events"

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

obj.
    addEventListener(
    "load"
    ,
     imgFetched)
    

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

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

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

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

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

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

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

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

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

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

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

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

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

2.2. Interface `Event`

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

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

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

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

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

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

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

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

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

A potential event target is null or an EventTarget object.

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

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

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

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

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

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

event = new Event(type [, eventInitDict]): Returns a new event whose type attribute value is set to type. The eventInitDict argument allows for setting the bubbles and cancelable attributes via object members of the same name.
event . type: Returns the type of event, e.g. "click", "hashchange", or "submit".
event . target: Returns the object to which event is dispatched (its target).
event . currentTarget: Returns the object whose event listener’s callback is currently being invoked.
event . composedPath(): Returns the invocation target objects of event’s path (objects on which listeners will be invoked), except for any nodes in shadow trees of which the shadow root’s mode is "closed" that are not reachable from event’s currentTarget.
event . eventPhase: Returns the event’s phase, which is one of NONE, CAPTURING_PHASE, AT_TARGET, and BUBBLING_PHASE.
event . stopPropagation(): When dispatched in a tree, invoking this method prevents event from reaching any objects other than the current object.
event . stopImmediatePropagation(): Invoking this method prevents event from reaching any registered event listeners after the current one finishes running and, when dispatched in a tree, also prevents event from reaching any other objects.
event . bubbles: Returns true or false depending on how event was initialized. True if event goes through its target’s ancestors in reverse tree order; otherwise false.
event . cancelable: Returns true or false depending on how event was initialized. Its return value does not always carry meaning, but true can indicate that part of the operation during which event was dispatched, can be canceled by invoking the preventDefault() method.
event . preventDefault(): If invoked when the cancelable attribute value is true, and while executing a listener for the event with passive set to false, signals to the operation that caused event to be dispatched that it needs to be canceled.
event . defaultPrevented: Returns true if preventDefault() was invoked successfully to indicate cancelation; otherwise false.
event . composed: Returns true or false depending on how event was initialized. True if event invokes listeners past a ShadowRoot node that is the root of its target; otherwise false.
event . isTrusted: Returns true if event was dispatched by the user agent, and false otherwise.
event . timeStamp: Returns the event’s timestamp as the number of milliseconds measured relative to the occurrence.

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

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

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

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

The composedPath() method steps are:

Let composedPath be an empty list.
Let path be this’s path.
If path is empty, then return composedPath.
Let currentTarget be this’s currentTarget attribute value.
Append currentTarget to composedPath.
Let currentTargetIndex be 0.
Let currentTargetHiddenSubtreeLevel be 0.
Let index be path’s size − 1.
While index is greater than or equal to 0:
1. If path[index]'s root-of-closed-tree is true, then increase currentTargetHiddenSubtreeLevel by 1.
2. If path[index]'s invocation target is currentTarget, then set currentTargetIndex to index and break.
3. If path[index]'s slot-in-closed-tree is true, then decrease currentTargetHiddenSubtreeLevel by 1.
4. Decrease index by 1.
Let currentHiddenLevel and maxHiddenLevel be currentTargetHiddenSubtreeLevel.
Set index to currentTargetIndex − 1.
While index is greater than or equal to 0:
1. If path[index]'s root-of-closed-tree is true, then increase currentHiddenLevel by 1.
2. If currentHiddenLevel is less than or equal to maxHiddenLevel, then prepend path[index]'s invocation target to composedPath.
3. If path[index]'s slot-in-closed-tree is true, then:
  1. Decrease currentHiddenLevel by 1.
  2. If currentHiddenLevel is less than maxHiddenLevel, then set maxHiddenLevel to currentHiddenLevel.
4. Decrease index by 1.
Set currentHiddenLevel and maxHiddenLevel to currentTargetHiddenSubtreeLevel.
Set index to currentTargetIndex + 1.
While index is less than path’s size:
1. If path[index]'s slot-in-closed-tree is true, then increase currentHiddenLevel by 1.
2. If currentHiddenLevel is less than or equal to maxHiddenLevel, then append path[index]'s invocation target to composedPath.
3. If path[index]'s root-of-closed-tree is true, then:
  1. Decrease currentHiddenLevel by 1.
  2. If currentHiddenLevel is less than maxHiddenLevel, then set maxHiddenLevel to currentHiddenLevel.
4. Increase index by 1.
Return composedPath.

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

NONE (numeric value 0): Events not currently dispatched are in this phase.
CAPTURING_PHASE (numeric value 1): When an event is dispatched to an object that participates in a tree it will be in this phase before it reaches its target.
AT_TARGET (numeric value 2): When an event is dispatched it will be in this phase on its target.
BUBBLING_PHASE (numeric value 3): When an event is dispatched to an object that participates in a tree it will be in this phase after it reaches its target.

Initially the attribute must be initialized to NONE.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Set event’s initialized flag.
Unset event’s stop propagation flag, stop immediate propagation flag, and canceled flag.
Set event’s isTrusted attribute to false.
Set event’s target to null.
Set event’s type attribute to type.
Set event’s bubbles attribute to bubbles.
Set event’s cancelable attribute to cancelable.

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

If this’s dispatch flag is set, then return.
Initialize this with type, bubbles, and cancelable.

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

2.3. Legacy extensions to the `Window` interface

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

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

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

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

2.4. Interface `CustomEvent`

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

  readonly
     attribute
     
     any
      
     detail
     ;

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

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

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

event = new CustomEvent(type [, eventInitDict]): Works analogously to the constructor for Event except that the eventInitDict argument now allows for setting the detail attribute too.
event . detail: Returns any custom data event was created with. Typically used for synthetic events.

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

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

If this’s dispatch flag is set, then return.
Initialize this with type, bubbles, and cancelable.
Set this’s detail attribute to detail.

2.5. Constructing events

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

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

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

Let event be the result of running the inner event creation steps with this interface, null, now, and eventInitDict.
Initialize event’s type attribute to type.
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:

If realm is not given, then set it to null.
Let dictionary be the result of converting the JavaScript value undefined to the dictionary type accepted by eventInterface’s constructor. (This dictionary type will either be EventInit or a dictionary that inherits from it.)
This does not work if members are required; see whatwg/dom#600.
Let event be the result of running the inner event creation steps with eventInterface, realm, the time of the occurrence that the event is signaling, and dictionary.
In macOS the time of the occurrence for input actions is available via the timestamp property of NSEvent objects.
Initialize event’s isTrusted attribute to true.
Return event.

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

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

Let event be the result of creating a new object using eventInterface. If realm is non-null, then use that realm; otherwise, use the default behavior defined in Web IDL.
As of the time of this writing Web IDL does not yet define any default behavior; see whatwg/webidl#135.
Set event’s initialized flag.
Initialize event’s timeStamp attribute to the relative high resolution coarse time given time and event’s relevant global object.
For each member → value in dictionary, if event has an attribute whose identifier is member, then initialize that attribute to value.
Run the event constructing steps with event and dictionary.
Return event.

2.6. Defining event interfaces

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

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

2.7. Interface `EventTarget`

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

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

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

dictionary
     
      EventListenerOptions
       {
  
     boolean
      
      capture
       = false
    ;
};

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

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

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

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

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

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

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

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

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

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

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

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

target = new EventTarget();

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

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

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

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

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

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

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

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

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

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

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

target . dispatchEvent(event)

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

To flatten options, run these steps:

If options is a boolean, then return options.
Return options["capture"].

To flatten more options, run these steps:

Let capture be the result of flattening options.
Let once be false.
Let passive and signal be null.
If options is a dictionary, then:
1. Set once to options["once"].
2. If options["passive"] exists, then set passive to options["passive"].
3. If options["signal"] exists, then set signal to options["signal"].
Return capture, passive, once, and signal.

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

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

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

The default passive value, given an event type type and an EventTarget eventTarget, is determined as follows:

Return true if all of the following are true:
- type is one of "touchstart", "touchmove", "wheel", or "mousewheel". [TOUCH-EVENTS] [UIEVENTS]
- eventTarget is a Window object, or is a node whose node document is eventTarget, or is a node whose node document’s document element is eventTarget, or is a node whose node document’s body element is eventTarget. [HTML]
Return false.

To add an event listener, given an EventTarget object eventTarget and an event listener listener, run these steps:

If eventTarget is a ServiceWorkerGlobalScope object, its service worker’s script resource’s has ever been evaluated flag is set, and listener’s type matches the type attribute value of any of the service worker events, then report a warning to the console that this might not give the expected results. [SERVICE-WORKERS]
If listener’s signal is not null and is aborted, then return.
If listener’s callback is null, then return.
If listener’s passive is null, then set it to the default passive value given listener’s type and eventTarget.
If eventTarget’s event listener list does not contain an event listener whose type is listener’s type, callback is listener’s callback, and capture is listener’s capture, then append listener to eventTarget’s event listener list.
If listener’s signal is not null, then add the following abort steps to it:
1. Remove an event listener with eventTarget and listener.

The add an event listener concept exists to ensure event handlers use the same code path. [HTML]

The addEventListener(type, callback, options) method steps are:

Let capture, passive, once, and signal be the result of flattening more options.
Add an event listener with this and an event listener whose type is type, callback is callback, capture is capture, passive is passive, once is once, and signal is signal.

To remove an event listener, given an EventTarget object eventTarget and an event listener listener, run these steps:

If eventTarget is a ServiceWorkerGlobalScope object and its service worker’s set of event types to handle contains listener’s type, then report a warning to the console that this might not give the expected results. [SERVICE-WORKERS]
Set listener’s removed to true and remove listener from eventTarget’s event listener list.

HTML needs this to define event handlers. [HTML]

To remove all event listeners, given an EventTarget object eventTarget, for each listener of eventTarget’s event listener list, remove an event listener with eventTarget and listener.

HTML needs this to define document.open(). [HTML]

The removeEventListener(type, callback, options) method steps are:

Let capture be the result of flattening options.
If this’s event listener list contains an event listener whose type is type, callback is callback, and capture is capture, then remove an event listener with this and that event listener.

The event listener list will not contain multiple event listeners with equal type, callback, and capture, as add an event listener prevents that.

The dispatchEvent(event) method steps are:

If event’s dispatch flag is set, or if its initialized flag is not set, then throw an "InvalidStateError" DOMException.
Initialize event’s isTrusted attribute to false.
Return the result of dispatching event to this.

2.8. Observing event listeners

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

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

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

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

Let callbacks be « ».
For each listener of global’s event listener list:
1. If listener’s type is "fetch", and listener’s callback is not null, then append listener’s callback to callbacks.
Return callbacks.

2.9. Dispatching events

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

Set event’s dispatch flag.
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.
Let activationTarget be null.
Let relatedTarget be the result of retargeting event’s relatedTarget against target.
If target is not relatedTarget or target is event’s relatedTarget, then:
1. Let touchTargets be a new list.
2. For each touchTarget of event’s touch target list, append the result of retargeting touchTarget against target to touchTargets.
3. Append to an event path with event, target, targetOverride, relatedTarget, touchTargets, and false.
4. Let isActivationEvent be true, if event is a MouseEvent object and event’s type attribute is "click"; otherwise false.
5. If isActivationEvent is true and target has activation behavior, then set activationTarget to target.
6. Let slottable be target, if target is a slottable and is assigned, and null otherwise.
7. Let slot-in-closed-tree be false.
8. Let parent be the result of invoking target’s get the parent with event.
9. While parent is non-null:
  1. If slottable is non-null:
    1. Assert: parent is a slot.
    2. Set slottable to null.
    3. If parent’s root is a shadow root whose mode is "closed", then set slot-in-closed-tree to true.
  2. If parent is a slottable and is assigned, then set slottable to parent.
  3. Let relatedTarget be the result of retargeting event’s relatedTarget against parent.
  4. Let touchTargets be a new list.
  5. For each touchTarget of event’s touch target list, append the result of retargeting touchTarget against parent to touchTargets.
  6. If parent is a Window object, or parent is a node and target’s root is a shadow-including inclusive ancestor of parent, then:
    1. If isActivationEvent is true, event’s bubbles attribute is true, activationTarget is null, and parent has activation behavior, then set activationTarget to parent.
    2. Append to an event path with event, parent, null, relatedTarget, touchTargets, and slot-in-closed-tree.
  7. Otherwise, if parent is relatedTarget, then set parent to null.
  8. Otherwise, set target to parent and then:
    1. If isActivationEvent is true, activationTarget is null, and target has activation behavior, then set activationTarget to target.
    2. Append to an event path with event, parent, target, relatedTarget, touchTargets, and slot-in-closed-tree.
  9. If parent is non-null, then set parent to the result of invoking parent’s get the parent with event.
  10. Set slot-in-closed-tree to false.
10. Let clearTargetsStruct be the last struct in event’s path whose shadow-adjusted target is non-null.
11. Let clearTargets be true if clearTargetsStruct’s shadow-adjusted target, clearTargetsStruct’s relatedTarget, or an EventTarget object in clearTargetsStruct’s touch target list is a node and its root is a shadow root; otherwise false.
12. If activationTarget is non-null and activationTarget has legacy-pre-activation behavior, then run activationTarget’s legacy-pre-activation behavior.
13. For each struct in event’s path, in reverse order:
  1. If struct’s shadow-adjusted target is non-null, then set event’s eventPhase attribute to AT_TARGET.
  2. Otherwise, set event’s eventPhase attribute to CAPTURING_PHASE.
  3. Invoke with struct, event, "capturing", and legacyOutputDidListenersThrowFlag if given.
14. For each struct in event’s path:
  1. If struct’s shadow-adjusted target is non-null, then set event’s eventPhase attribute to AT_TARGET.
  2. Otherwise:
    1. If event’s bubbles attribute is false, then continue.
    2. Set event’s eventPhase attribute to BUBBLING_PHASE.
  3. Invoke with struct, event, "bubbling", and legacyOutputDidListenersThrowFlag if given.
Set event’s eventPhase attribute to NONE.
Set event’s currentTarget attribute to null.
Set event’s path to the empty list.
Unset event’s dispatch flag, stop propagation flag, and stop immediate propagation flag.
If clearTargets, then:
1. Set event’s target to null.
2. Set event’s relatedTarget to null.
3. Set event’s touch target list to the empty list.
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.
Return false if event’s canceled flag is set; otherwise true.

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

Let invocationTargetInShadowTree be false.
If invocationTarget is a node and its root is a shadow root, then set invocationTargetInShadowTree to true.
Let root-of-closed-tree be false.
If invocationTarget is a shadow root whose mode is "closed", then set root-of-closed-tree to true.
Append a new struct to event’s path whose invocation target is invocationTarget, invocation-target-in-shadow-tree is invocationTargetInShadowTree, shadow-adjusted target is shadowAdjustedTarget, relatedTarget is relatedTarget, touch target list is touchTargets, root-of-closed-tree is root-of-closed-tree, and slot-in-closed-tree is slot-in-closed-tree.

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

Set event’s target to the shadow-adjusted target of the last struct in event’s path, that is either struct or preceding struct, whose shadow-adjusted target is non-null.
Set event’s relatedTarget to struct’s relatedTarget.
Set event’s touch target list to struct’s touch target list.
If event’s stop propagation flag is set, then return.
Initialize event’s currentTarget attribute to struct’s invocation target.
Let listeners be a clone of event’s currentTarget attribute value’s event listener list.
This avoids event listeners added after this point from being run. Note that removal still has an effect due to the removed field.
Let invocationTargetInShadowTree be struct’s invocation-target-in-shadow-tree.
Let found be the result of running inner invoke with event, listeners, phase, invocationTargetInShadowTree, and legacyOutputDidListenersThrowFlag if given.

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

Let originalEventType be event’s type attribute value.

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`"

Inner invoke with event, listeners, phase, invocationTargetInShadowTree, and legacyOutputDidListenersThrowFlag if given.
Set event’s type attribute value to originalEventType.

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

Let found be false.
For each listener in listeners, whose removed is false:
1. If event’s type attribute value is not listener’s type, then continue.
2. Set found to true.
3. If phase is "capturing" and listener’s capture is false, then continue.
4. If phase is "bubbling" and listener’s capture is true, then continue.
5. If listener’s once is true, then remove listener from event’s currentTarget attribute value’s event listener list.
6. Let global be listener callback’s associated realm’s global object.
7. Let currentEvent be undefined.
8. If global is a Window object, then:
  1. Set currentEvent to global’s current event.
  2. If invocationTargetInShadowTree is false, then set global’s current event to event.
9. If listener’s passive is true, then set event’s in passive listener flag.
10. If global is a Window object, then record timing info for event listener given event and listener.
11. Call a user object’s operation with listener’s callback, "handleEvent", « event », and event’s currentTarget attribute value. If this throws an exception, then:
  1. Report the exception.
  2. Set legacyOutputDidListenersThrowFlag if given.
    The legacyOutputDidListenersThrowFlag is only used by Indexed Database API. [INDEXEDDB]
12. Unset event’s in passive listener flag.
13. If global is a Window object, then set global’s current event to currentEvent.
14. If event’s stop immediate propagation flag is set, then return found.
Return found.

2.10. Firing events

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

If eventConstructor is not given, then let eventConstructor be Event.
Let event be the result of creating an event given eventConstructor, in the relevant realm of target.
Initialize event’s type attribute to e.
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.
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.

If the event needs its bubbles or cancelable attribute initialized, one could write "fire an event named submit at target with its cancelable attribute initialized to true".

Or, when a custom constructor is needed, "fire an event named click at target using MouseEvent with its detail attribute initialized to 1".

Occasionally the return value is important:

Let doAction be the result of firing an event named like at target.
If doAction is true, then …

2.11. Action versus occurrence

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

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

3. Aborting ongoing activities

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

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

A hypothetical doAmazingness({ ... }) method could accept an AbortSignal object to support aborting as follows:


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

doAmazingness could be implemented as follows:


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

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

      }

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

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

3.1. Interface `AbortController`

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

  [
     SameObject
     ] readonly
     attribute
     
     AbortSignal
      
     signal
     ;

  
     undefined
      
     abort
     (optional
     
     any
      
      reason
      );
};

controller = new AbortController(): Returns a new controller whose signal is set to a newly created AbortSignal object.
controller . signal: Returns the AbortSignal object associated with this object.
controller . abort(reason): Invoking this method will store reason in this object’s AbortSignal's abort reason, and signal to any observers that the associated activity is to be aborted. If reason is undefined, then an "AbortError" DOMException will be stored.

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

The new AbortController() constructor steps are:

Let signal be a new AbortSignal object.
Set this’s signal to signal.

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

The abort(reason) method steps are to signal abort on this with reason if it is given.

To signal abort on an AbortController controller with an optional reason, signal abort on controller’s signal with reason if it is given.

3.2. Interface `AbortSignal`

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

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

  attribute
     
     EventHandler
      
     onabort
     ;
};

AbortSignal . abort(reason): Returns an AbortSignal instance whose abort reason is set to reason if not undefined; otherwise to an "AbortError" DOMException.
AbortSignal . any(signals): Returns an AbortSignal instance which will be aborted once any of signals is aborted. Its abort reason will be set to whichever one of signals caused it to be aborted.
AbortSignal . timeout(milliseconds): Returns an AbortSignal instance which will be aborted in milliseconds milliseconds. Its abort reason will be set to a "TimeoutError" DOMException.
signal . aborted: Returns true if signal’s AbortController has signaled to abort; otherwise false.
signal . reason: Returns signal’s abort reason.
signal . throwIfAborted(): Throws signal’s abort reason, if signal’s AbortController has signaled to abort; otherwise, does nothing.

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

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

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

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

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

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

The static abort(reason) method steps are:

Let signal be a new AbortSignal object.
Set signal’s abort reason to reason if it is given; otherwise to a new "AbortError" DOMException.
Return signal.

The static timeout(milliseconds) method steps are:

Let signal be a new AbortSignal object.
Let global be signal’s relevant global object.
Run steps after a timeout given global, "AbortSignal-timeout", milliseconds, and the following step:
1. Queue a global task on the timer task source given global to signal abort given signal and a new "TimeoutError" DOMException.
For the duration of this timeout, if signal has any event listeners registered for its abort event, there must be a strong reference from global to signal.
Return signal.

The static any(signals) method steps are to return the result of creating a dependent abort signal from signals using AbortSignal and the current realm.

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

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

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

This method is primarily useful for when functions accepting AbortSignals want to throw (or return a rejected promise) at specific checkpoints, instead of passing along the AbortSignal to other methods. For example, the following function allows aborting in between each attempt to poll for a condition. This gives opportunities to abort the polling process, even though the actual asynchronous operation (i.e., await func ()) does not accept an AbortSignal.

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

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

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

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

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

To add an algorithm algorithm to an AbortSignal object signal:

If signal is aborted, then return.
Append algorithm to signal’s abort algorithms.

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

To signal abort, given an AbortSignal object signal and an optional reason:

If signal is aborted, then return.
Set signal’s abort reason to reason if it is given; otherwise to a new "AbortError" DOMException.
For each algorithm of signal’s abort algorithms: run algorithm.
Empty signal’s abort algorithms.
Fire an event named abort at signal.
For each dependentSignal of signal’s dependent signals, signal abort on dependentSignal with signal’s abort reason.

To create a dependent abort signal from a list of AbortSignal objects signals, using signalInterface, which must be either AbortSignal or an interface that inherits from it, and a realm:

Let resultSignal be a new object implementing signalInterface using realm.
For each signal of signals: if signal is aborted, then set resultSignal’s abort reason to signal’s abort reason and return resultSignal.
Set resultSignal’s dependent to true.
For each signal of signals:
1. If signal’s dependent is false, then:
  1. Append signal to resultSignal’s source signals.
  2. Append resultSignal to signal’s dependent signals.
2. Otherwise, for each sourceSignal of signal’s source signals:
  1. Assert: sourceSignal is not aborted and not dependent.
  2. Append sourceSignal to resultSignal’s source signals.
  3. Append resultSignal to sourceSignal’s dependent signals.
Return resultSignal.

3.2.1. Garbage collection

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

3.3. Using `AbortController` and `AbortSignal` objects in APIs

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

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

The method steps for a promise-returning method doAmazingness(options) could be as follows:

Let p be a new promise.
If options["signal"] member is present, then:
1. Let signal be options["signal"].
2. If signal is aborted, then reject p with signal’s abort reason and return p.
3. Add the following abort steps to signal:
  1. Stop doing amazing things.
  2. Reject p with signal’s abort reason.
Run these steps in parallel:
1. Let amazingResult be the result of doing some amazing things.
2. Resolve p with amazingResult.
Return p.

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

4. Nodes

4.1. Introduction to "The DOM"

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

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

To illustrate, consider this HTML document:

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

It is represented as follows:

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

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

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

4.2. Node tree

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

In practice you deal with more specific objects.

Objects that implement Node also implement an inherited interface: Document, DocumentType, DocumentFragment, Element, CharacterData, or Attr.

Objects that implement DocumentFragment sometimes implement ShadowRoot.

Objects that implement Element also typically implement an inherited interface, such as HTMLAnchorElement.

Objects that implement CharacterData also implement an inherited interface: Text, ProcessingInstruction, or Comment.

Objects that implement Text sometimes implement CDATASection.

Thus, every node's primary interface is one of: Document, DocumentType, DocumentFragment, ShadowRoot, Element or an inherited interface of Element, Attr, Text, CDATASection, ProcessingInstruction, or Comment.

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

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

Document

In tree order:

Zero or more ProcessingInstruction or Comment nodes.
Optionally one DocumentType node.
Zero or more ProcessingInstruction or Comment nodes.
Optionally one Element node.
Zero or more ProcessingInstruction or Comment nodes.

DocumentFragment

Element

Zero or more Element or CharacterData nodes.

DocumentType

CharacterData

Attr

No children.

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

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

If node is a DocumentType or Attr node, then return 0.
If node is a CharacterData node, then return node’s data’s length.
Return the number of node’s children.

A node is considered empty if its length is 0.

4.2.1. Document tree

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

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

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

A node is in a document tree if its root is a document.

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

A node 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:

If element is a slot, localName is name, and namespace is null, then:
1. If value is oldValue, then return.
2. If value is null and oldValue is the empty string, then return.
3. If value is the empty string and oldValue is null, then return.
4. If value is null or the empty string, then set element’s name to the empty string.
5. Otherwise, set element’s name to value.
6. Run assign slottables for a tree with element’s root.

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

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

4.2.2.2. Slottables

Element and Text nodes are slottables.

A slot can be a slottable.

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

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

If localName is slot and namespace is null, then:
1. If value is oldValue, then return.
2. If value is null and oldValue is the empty string, then return.
3. If value is the empty string and oldValue is null, then return.
4. If value is null or the empty string, then set element’s name to the empty string.
5. Otherwise, set element’s name to value.
6. If element is assigned, then run assign slottables for element’s assigned slot.
7. Run assign a slot for element.

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

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

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

4.2.2.3. Finding slots and slottables

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

If slottable’s parent is null, then return null.
Let shadow be slottable’s parent’s shadow root.
If shadow is null, then return null.
If the open flag is set and shadow’s mode is not "open", then return null.
If shadow’s slot assignment is "manual", then return the slot in shadow’s descendants whose manually assigned nodes contains slottable, if any; otherwise null.
Return the first slot in tree order in shadow’s descendants whose name is slottable’s name, if any; otherwise null.

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

Let result be an empty list.
Let root be slot’s root.
If root is not a shadow root, then return result.
Let host be root’s host.
If root’s slot assignment is "manual", then:
1. Let result be « ».
2. For each slottable slottable of slot’s manually assigned nodes, if slottable’s parent is host, append slottable to result.
Otherwise, for each slottable child slottable of host, in tree order:
1. Let foundSlot be the result of finding a slot given slottable.
2. If foundSlot is slot, then append slottable to result.
Return result.

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

Let result be an empty list.
If slot’s root is not a shadow root, then return result.
Let slottables be the result of finding slottables given slot.
If slottables is the empty list, then append each slottable child of slot, in tree order, to slottables.
For each node in slottables:
1. If node is a slot whose root is a shadow root, then:
  1. Let temporaryResult be the result of finding flattened slottables given node.
  2. Append each slottable in temporaryResult, in order, to result.
2. Otherwise, append node to result.
Return result.

4.2.2.4. Assigning slottables and slots

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

Let slottables be the result of finding slottables for slot.
If slottables and slot’s assigned nodes are not identical, then run signal a slot change for slot.
Set slot’s assigned nodes to slottables.
For each slottable in slottables, set slottable’s assigned slot to slot.

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

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

Let slot be the result of finding a slot with slottable.
If slot is non-null, then run assign slottables for slot.

4.2.2.5. Signaling slot change

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

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

Append slot to slot’s relevant agent’s signal slots.
Queue a mutation observer microtask.

4.2.3. Mutation algorithms

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

If parent is not a Document, DocumentFragment, or Element node, then throw a "HierarchyRequestError" DOMException.
If node is a host-including inclusive ancestor of parent, then throw a "HierarchyRequestError" DOMException.
If child is non-null and its parent is not parent, then throw a "NotFoundError" DOMException.
If node is not a DocumentFragment, DocumentType, Element, or CharacterData node, then throw a "HierarchyRequestError" DOMException.
If either node is a Text node and parent is a document, or node is a doctype and parent is not a document, then throw a "HierarchyRequestError" DOMException.
If parent is a document, and any of the statements below, switched on the interface node implements, are true, then throw a "HierarchyRequestError" DOMException.

DocumentFragment

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

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

Element

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

DocumentType

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

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

Ensure pre-insertion validity of node into parent before child.
Let referenceChild be child.
If referenceChild is node, then set referenceChild to node’s next sibling.
Insert node into parent before referenceChild.
Return node.

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

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

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

Let nodes be node’s children, if node is a DocumentFragment node; otherwise « node ».
Let count be nodes’s size.
If count is 0, then return.
If node is a DocumentFragment node, then:
1. Remove its children with the suppress observers flag set.
2. Queue a tree mutation record for node with « », nodes, null, and null.
  This step intentionally does not pay attention to the suppress observers flag.
If child is non-null, then:
1. For each live range whose start node is parent and start offset is greater than child’s index, increase its start offset by count.
2. For each live range whose end node is parent and end offset is greater than child’s index, increase its end offset by count.
Let previousSibling be child’s previous sibling or parent’s last child if child is null.
For each node in nodes, in tree order:
1. Adopt node into parent’s node document.
2. If child is null, then append node to parent’s children.
3. Otherwise, insert node into parent’s children before child’s index.
4. If parent is a shadow host whose shadow root’s slot assignment is "named" and node is a slottable, then assign a slot for node.
5. If parent’s root is a shadow root, and parent is a slot whose assigned nodes is the empty list, then run signal a slot change for parent.
6. Run assign slottables for a tree with node’s root.
7. For each shadow-including inclusive descendant inclusiveDescendant of node, in shadow-including tree order:
  1. Run the insertion steps with inclusiveDescendant.
  2. If inclusiveDescendant is connected, then:
    1. If inclusiveDescendant is custom, then enqueue a custom element callback reaction with inclusiveDescendant, callback name "connectedCallback", and an empty argument list.
    2. Otherwise, try to upgrade inclusiveDescendant.
      If this successfully upgrades inclusiveDescendant, its connectedCallback will be enqueued automatically during the upgrade an element algorithm.
If suppress observers flag is unset, then queue a tree mutation record for parent with nodes, « », previousSibling, and child.
Run the children changed steps for parent.

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

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

If parent is not a Document, DocumentFragment, or Element node, then throw a "HierarchyRequestError" DOMException.
If node is a host-including inclusive ancestor of parent, then throw a "HierarchyRequestError" DOMException.
If child’s parent is not parent, then throw a "NotFoundError" DOMException.
If node is not a DocumentFragment, DocumentType, Element, or CharacterData node, then throw a "HierarchyRequestError" DOMException.
If either node is a Text node and parent is a document, or node is a doctype and parent is not a document, then throw a "HierarchyRequestError" DOMException.
If parent is a document, and any of the statements below, switched on the interface node implements, are true, then throw a "HierarchyRequestError" DOMException.

DocumentFragment

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

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

Element

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

DocumentType

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

The above statements differ from the pre-insert algorithm.
Let referenceChild be child’s next sibling.
If referenceChild is node, then set referenceChild to node’s next sibling.
Let previousSibling be child’s previous sibling.
Let removedNodes be the empty set.
If child’s parent is non-null, then:
1. Set removedNodes to « child ».
2. Remove child with the suppress observers flag set.
The above can only be false if child is node.
Let nodes be node’s children if node is a DocumentFragment node; otherwise « node ».
Insert node into parent before referenceChild with the suppress observers flag set.
Queue a tree mutation record for parent with nodes, removedNodes, previousSibling, and referenceChild.
Return child.

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

Let removedNodes be parent’s children.
Let addedNodes be the empty set.
If node is a DocumentFragment node, then set addedNodes to node’s children.
Otherwise, if node is non-null, set addedNodes to « node ».
Remove all parent’s children, in tree order, with the suppress observers flag set.
If node is non-null, then insert node into parent before null with the suppress observers flag set.
If either addedNodes or removedNodes is not empty, then queue a tree mutation record for parent with addedNodes, removedNodes, null, and null.

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

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

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

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

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

Let parent be node’s parent.
Assert: parent is non-null.
Let index be node’s index.
For each live range whose start node is an inclusive descendant of node, set its start to (parent, index).
For each live range whose end node is an inclusive descendant of node, set its end to (parent, index).
For each live range whose start node is parent and start offset is greater than index, decrease its start offset by 1.
For each live range whose end node is parent and end offset is greater than index, decrease its end offset by 1.
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.
Let oldPreviousSibling be node’s previous sibling.
Let oldNextSibling be node’s next sibling.
Remove node from its parent’s children.
If node is assigned, then run assign slottables for node’s assigned slot.
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.
If node has an inclusive descendant that is a slot, then:
1. Run assign slottables for a tree with parent’s root.
2. Run assign slottables for a tree with node.
Run the removing steps with node and parent.
Let isParentConnected be parent’s connected.
If node is custom and isParentConnected is true, then enqueue a custom element callback reaction with node, callback name "disconnectedCallback", and an empty argument list.
It is intentional for now that custom elements do not get parent passed. This might change in the future if there is a need.
For each shadow-including descendant descendant of node, in shadow-including tree order, then:
1. Run the removing steps with descendant and null.
2. If descendant is custom and isParentConnected is true, then enqueue a custom element callback reaction with descendant, callback name "disconnectedCallback", and an empty argument list.
For each inclusive ancestor inclusiveAncestor of parent, and then for each registered of inclusiveAncestor’s registered observer list, if registered’s options["subtree"] is true, then append a new transient registered observer whose observer is registered’s observer, options is registered’s options, and source is registered to node’s registered observer list.
If suppress observers flag is unset, then queue a tree mutation record for parent with « », « node », oldPreviousSibling, and oldNextSibling.
Run the children changed steps for parent.

4.2.4. Mixin `NonElementParentNode`

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

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

     Document
      includes
     
     NonElementParentNode
     ;

     DocumentFragment
      includes
     
     NonElementParentNode
     ;

node . getElementById(elementId): Returns the first element within node’s descendants whose ID is elementId.

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

4.2.5. Mixin `DocumentOrShadowRoot`

    interface
     mixin
     
      DocumentOrShadowRoot
       {
};

     Document
      includes
     
     DocumentOrShadowRoot
     ;

     ShadowRoot
      includes
     
     DocumentOrShadowRoot
     ;

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

4.2.6. Mixin `ParentNode`

To convert nodes into a node, given a node parent, list of nodes nodes, and document document:

Let node be null.
Replace each string in nodes with a new Text node whose data is the string and node document is document.
Let isScriptElement be true if parent is an HTMLScriptElement node; otherwise false.
Let newNodes be « ».
For each value of nodes:
1. Let newValue be value.
2. If value is a Text node and isScriptElement is true, then set newValue to a new Text node whose node document is document and data is the result of calling Get Trusted Type compliant string, with TrustedScript, document’s relevant global object, value’s data, "HTMLScriptElement text", and "script".
3. If value is a TrustedScript, then set newValue to a new Text node whose data is value’s data and node document is document.
4. Append newValue to newNodes.
If newNodes contains one node, then set node to newNodes[0].
Otherwise, set node to a new DocumentFragment node whose node document is document, and then append each node in newNodes, if any, to it.
Return node.

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

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

  
     Element
     ? 
     querySelector
     (
     DOMString
      
      selectors
      );
  [
     NewObject
     ] 
     NodeList
      
     querySelectorAll
     (
     DOMString
      
      selectors
      );
};

     Document
      includes
     
     ParentNode
     ;

     DocumentFragment
      includes
     
     ParentNode
     ;

     Element
      includes
     
     ParentNode
     ;

collection = node . children

Returns the child elements.

element = node . firstElementChild

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

element = node . lastElementChild

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

node . prepend(nodes)

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

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

node . append(nodes)

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

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

node . replaceChildren(nodes)

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

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

node . querySelector(selectors)

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

node . querySelectorAll(selectors)

Returns all element descendants of node that match selectors.

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

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

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

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

The prepend(nodes) method steps are:

Let node be the result of converting nodes into a node given this, nodes, and this’s node document.
Pre-insert node into this before this’s first child.

The append(nodes) method steps are:

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

The replaceChildren(nodes) method steps are:

Let node be the result of converting nodes into a node given this, nodes, and this’s node document.
Ensure pre-insertion validity of node into this before null.
Replace all with node within this.

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

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

4.2.7. Mixin `NonDocumentTypeChildNode`

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

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

     Element
      includes
     
     NonDocumentTypeChildNode
     ;

     CharacterData
      includes
     
     NonDocumentTypeChildNode
     ;

element = node . previousElementSibling: Returns the first preceding sibling that is an element; otherwise null.
element = node . nextElementSibling: Returns the first following sibling that is an element; otherwise null.

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

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

4.2.8. Mixin `ChildNode`

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

     DocumentType
      includes
     
     ChildNode
     ;

     Element
      includes
     
     ChildNode
     ;

     CharacterData
      includes
     
     ChildNode
     ;

node . before(...nodes)

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

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

node . after(...nodes)

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

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

node . replaceWith(...nodes)

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

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

node . remove()

Removes node.

The before(nodes) method steps are:

Let parent be this’s parent.
If parent is null, then return.
Let viablePreviousSibling be this’s first preceding sibling not in nodes; otherwise null.
Let node be the result of converting nodes into a node, given parent, nodes, and this’s node document.
If viablePreviousSibling is null, then set it to parent’s first child; otherwise to viablePreviousSibling’s next sibling.
Pre-insert node into parent before viablePreviousSibling.

The after(nodes) method steps are:

Let parent be this’s parent.
If parent is null, then return.
Let viableNextSibling be this’s first following sibling not in nodes; otherwise null.
Let node be the result of converting nodes into a node, given parent, nodes, and this’s node document.
Pre-insert node into parent before viableNextSibling.

The replaceWith(nodes) method steps are:

Let parent be this’s parent.
If parent is null, then return.
Let viableNextSibling be this’s first following sibling not in nodes; otherwise null.
Let node be the result of converting nodes into a node, given parent, nodes, and this’s node document.
If this’s parent is parent, replace this with node within parent.
This could have been inserted into node.
Otherwise, pre-insert node into parent before viableNextSibling.

The remove() method steps are:

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

4.2.9. Mixin `Slottable`

    interface
     mixin
     
      Slottable
       {
  readonly
     attribute
     
     HTMLSlotElement
     ? 
     assignedSlot
     ;
};

     Element
      includes
     
     Slottable
     ;

     Text
      includes
     
     Slottable
     ;

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

4.2.10. Old-style collections: `NodeList` and `HTMLCollection`

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

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

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

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

4.2.10.1. Interface `NodeList`

A NodeList object is a collection of nodes.

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

collection . length: Returns the number of nodes in the collection.
element = collection . item(index)
element = collection[index]: Returns the node with index index from the collection. The nodes are sorted in tree order.

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

The length attribute must return the number of nodes represented by the collection.

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

4.2.10.2. Interface `HTMLCollection`

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

An HTMLCollection object is a collection of elements.

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

collection . length: Returns the number of elements in the collection.
element = collection . item(index)
element = collection[index]: Returns the element with index index from the collection. The elements are sorted in tree order.
element = collection . namedItem(name)
element = collection[name]: Returns the first element with ID or name name from the collection.

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

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

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

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

Let result be an empty list.
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.
Return result.

The namedItem(key) method steps are:

If key is the empty string, return null.
Return the first element in the collection for which at least one of the following is true:
- it has an ID which is key;
- it is in the HTML namespace and has a name attribute whose value is key;
or null if there is no such element.

4.3. Mutation observers

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

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

To queue a mutation observer microtask, run these steps:

If the surrounding agent’s mutation observer microtask queued is true, then return.
Set the surrounding agent’s mutation observer microtask queued to true.
Queue a microtask to notify mutation observers.

To notify mutation observers, run these steps:

Set the surrounding agent’s mutation observer microtask queued to false.
Let notifySet be a clone of the surrounding agent’s pending mutation observers.
Empty the surrounding agent’s pending mutation observers.
Let signalSet be a clone of the surrounding agent’s signal slots.
Empty the surrounding agent’s signal slots.
For each mo of notifySet:
1. Let records be a clone of mo’s record queue.
2. Empty mo’s record queue.
3. For each node of mo’s node list, remove all transient registered observers whose observer is mo from node’s registered observer list.
4. If records is not empty, then invoke mo’s callback with « records, mo », and mo. If this throws an exception, catch it, and report the exception.
For each slot of signalSet, fire an event named slotchange, with its bubbles attribute set to true, at slot.

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

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

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

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

4.3.1. Interface `MutationObserver`

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

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

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

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

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

Each MutationObserver object has these associated concepts:

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

observer = new MutationObserver(callback)

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

observer . observe(target, options)

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

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

childList: Set to true if mutations to target’s children are to be observed.
attributes: Set to true if mutations to target’s attributes are to be observed. Can be omitted if attributeOldValue or attributeFilter is specified.
characterData: Set to true if mutations to target’s data are to be observed. Can be omitted if characterDataOldValue is specified.
subtree: Set to true if mutations to not just target, but also target’s descendants are to be observed.
attributeOldValue: Set to true if attributes is true or omitted and target’s attribute value before the mutation needs to be recorded.
characterDataOldValue: Set to true if characterData is set to true or omitted and target’s data before the mutation needs to be recorded.
attributeFilter: Set to a list of attribute local names (without namespace) if not all attribute mutations need to be observed and attributes is true or omitted.

observer . disconnect()

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

observer . takeRecords()

Empties the record queue and returns what was in there.

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

The observe(target, options) method steps are:

If either options["attributeOldValue"] or options["attributeFilter"] exists, and options["attributes"] does not exist, then set options["attributes"] to true.
If options["characterDataOldValue"] exists and options["characterData"] does not exist, then set options["characterData"] to true.
If none of options["childList"], options["attributes"], and options["characterData"] is true, then throw a TypeError.
If options["attributeOldValue"] is true and options["attributes"] is false, then throw a TypeError.
If options["attributeFilter"] is present and options["attributes"] is false, then throw a TypeError.
If options["characterDataOldValue"] is true and options["characterData"] is false, then throw a TypeError.
For each registered of target’s registered observer list, if registered’s observer is this:
1. For each node of this’s node list, remove all transient registered observers whose source is registered from node’s registered observer list.
2. Set registered’s options to options.
Otherwise:
1. Append a new registered observer whose observer is this and options is options to target’s registered observer list.
2. Append a weak reference to target to this’s node list.

The disconnect() method steps are:

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

The takeRecords() method steps are:

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

4.3.2. Queuing a mutation record

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

Let interestedObservers be an empty map.
Let nodes be the inclusive ancestors of target.
For each node in nodes, and then for each registered of node’s registered observer list:
1. Let options be registered’s options.
2. If none of the following are true
  - node is not target and options["subtree"] is false
  - type is "attributes" and options["attributes"] either does not exist or is false
  - type is "attributes", options["attributeFilter"] exists, and options["attributeFilter"] does not contain name or namespace is non-null
  - type is "characterData" and options["characterData"] either does not exist or is false
  - type is "childList" and options["childList"] is false
  then:
  1. Let mo be registered’s observer.
  2. If interestedObservers[mo] does not exist, then set interestedObservers[mo] to null.
  3. If either type is "attributes" and options["attributeOldValue"] is true, or type is "characterData" and options["characterDataOldValue"] is true, then set interestedObservers[mo] to oldValue.
For each observer → mappedOldValue of interestedObservers:
1. Let record be a new MutationRecord object with its type set to type, target set to target, attributeName set to name, attributeNamespace set to namespace, oldValue set to mappedOldValue, addedNodes set to addedNodes, removedNodes set to removedNodes, previousSibling set to previousSibling, and nextSibling set to nextSibling.
2. Enqueue record to observer’s record queue.
3. Append observer to the surrounding agent’s pending mutation observers.
Queue a mutation observer microtask.

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

Assert: either addedNodes or removedNodes is not empty.
Queue a mutation record of "childList" for target with null, null, null, addedNodes, removedNodes, previousSibling, and nextSibling.

4.3.3. Interface `MutationRecord`

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

record . type: Returns "attributes" if it was an attribute mutation. "characterData" if it was a mutation to a CharacterData node. And "childList" if it was a mutation to the tree of nodes.
record . target: Returns the node the mutation affected, depending on the type. For "attributes", it is the element whose attribute changed. For "characterData", it is the CharacterData node. For "childList", it is the node whose children changed.
record . addedNodes
record . removedNodes: Return the nodes added and removed respectively.
record . previousSibling
record . nextSibling: Return the previous and next sibling respectively of the added or removed nodes; otherwise null.
record . attributeName: Returns the local name of the changed attribute; otherwise null.
record . attributeNamespace: Returns the namespace of the changed attribute; otherwise null.
record . oldValue: The return value depends on type. For "attributes", it is the value of the changed attribute before the change. For "characterData", it is the data of the changed node before the change. For "childList", it is null.

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

4.4. Interface `Node`

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

  readonly
     attribute
     
     USVString
      
     baseURI
     ;

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

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

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

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

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

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

dictionary
     
      GetRootNodeOptions
       {
  
     boolean
      
      composed
       = false
    ;
};

Node is an abstract interface that is used by all nodes. You cannot get a direct instance of it.

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; otherwise node’s parent.

Each node also has a registered observer list.

node . nodeType

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

Element: Node . ELEMENT_NODE (1).
Attr: Node . ATTRIBUTE_NODE (2).
An exclusive Text node: Node . TEXT_NODE (3).
CDATASection: Node . CDATA_SECTION_NODE (4).
ProcessingInstruction: Node . PROCESSING_INSTRUCTION_NODE (7).
Comment: Node . COMMENT_NODE (8).
Document: Node . DOCUMENT_NODE (9).
DocumentType: Node . DOCUMENT_TYPE_NODE (10).
DocumentFragment: Node . DOCUMENT_FRAGMENT_NODE (11).

node . nodeName

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

Element: Its HTML-uppercased qualified name.
Attr: Its qualified name.
An exclusive Text node: "#text".
CDATASection: "#cdata-section".
ProcessingInstruction: Its target.
Comment: "#comment".
Document: "#document".
DocumentType: Its name.
DocumentFragment: "#document-fragment".

The nodeType getter steps are to return the first matching statement, switching on the interface this implements:

Element: ELEMENT_NODE (1)
Attr: ATTRIBUTE_NODE (2);
An exclusive Text node: 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 getter steps are to return the first matching statement, switching on the interface this implements:

Element: Its HTML-uppercased qualified name.
Attr: Its qualified name.
An exclusive Text node: "#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 getter steps are to return this’s node document’s document base URL, serialized.

node . isConnected: Returns true if node is connected; otherwise false.
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 getter steps are to return true, if this is connected; otherwise false.

The ownerDocument getter steps are to return null, if this is a document; otherwise this’s node document.

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

The getRootNode(options) method steps are to return this’s shadow-including root if options["composed"] is true; otherwise this’s root.

The parentNode getter steps are to return this’s parent.

The parentElement getter steps are to return this’s parent element.

The hasChildNodes() method steps are to return true if this has children; otherwise false.

The childNodes getter steps are to return a NodeList rooted at this matching only children.

The firstChild getter steps are to return this’s first child.

The lastChild getter steps are to return this’s last child.

The previousSibling getter steps are to return this’s previous sibling.

The nextSibling getter steps are to return this’s next sibling.

The nodeValue getter steps are to return the following, switching on the interface this implements:

Attr: this’s value.
CharacterData: this’s data.
Otherwise: Null.

The nodeValue setter steps are to, if the given value is null, act as if it was the empty string instead, and then do as described below, switching on the interface this implements:

Attr: Set an existing attribute value with this and the given value.
CharacterData: Replace data with node this, offset 0, count this’s length, and data the given value.
Otherwise: Do nothing.

To get text content with a node node, return the following, switching on the interface node implements:

DocumentFragment
Element: The descendant text content of node.
Attr: node’s value.
CharacterData: node’s data.
Otherwise: Null.

The textContent getter steps are to return the result of running get text content with this.

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

Let node be null.
If string is not the empty string, then set node to a new Text node whose data is string and node document is parent’s node document.
Replace all with node within parent.

To set text content with a node node and a string value, do as defined below, switching on the interface node implements:

DocumentFragment
Element: String replace all with value within node.
Attr: Set an existing attribute value with node and value.
CharacterData: Replace data with node node, offset 0, count node’s length, and data value.
Otherwise: Do nothing.

The textContent setter steps are to, if the given value is null, act as if it was the empty string instead, and then run set text content with this and the given value.

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 steps are to run these steps for each descendant exclusive Text node node of this:

Let length be node’s length.
If length is zero, then remove node and continue with the next exclusive Text node, if any.
Let data be the concatenation of the data of node’s contiguous exclusive Text nodes (excluding itself), in tree order.
Replace data with node node, offset length, count 0, and data data.
Let currentNode be node’s next sibling.
While currentNode is an exclusive Text node:
1. For each live range whose start node is currentNode, add length to its start offset and set its start node to node.
2. For each live range whose end node is currentNode, add length to its end offset and set its end node to node.
3. For each live 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 live 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.
Remove node’s contiguous exclusive Text nodes (excluding itself), in tree order.

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.

Specifications may define cloning steps for all or some nodes. The algorithm is passed copy, node, document, and an optional clone children flag, as indicated in the clone algorithm.

HTML defines cloning steps for script and input elements. SVG ought to do the same for its script elements, but does not call this out at the moment.

To clone a node, with an optional document and clone children flag, run these steps:

If document is not given, let document be node’s node document.
If node is an element, then:
1. Let copy be the result of creating an element, given document, node’s local name, node’s namespace, node’s namespace prefix, and node’s is value, with the synchronous custom elements flag unset.
2. For each attribute in node’s attribute list:
  1. Let copyAttribute be a clone of attribute.
  2. Append copyAttribute to copy.
Otherwise, let copy be a node that implements the same interfaces as node, and fulfills these additional requirements, switching on the interface node implements:

Document

Set copy’s encoding, content type, URL, origin, type, and mode to those of node.

DocumentType

Set copy’s name, public ID, and system ID to those of node.

Attr

Set copy’s namespace, namespace prefix, local name, and value to those of node.

Text

Comment

Set copy’s data to that of node.

ProcessingInstruction

Set copy’s target and data to those of node.

Otherwise

Do nothing.
Set copy’s node document and document to copy, if copy is a document, and set copy’s node document to document otherwise.
Run any cloning steps defined for node in other applicable specifications and pass copy, node, document, and the clone children flag if set, as parameters.
If the clone children flag is set, then for each child child of node, in tree order: append the result of cloning child with document and the clone children flag set, to copy.
If node is a shadow host whose shadow root’s clonable is true:
1. Assert: copy is not a shadow host.
2. Run attach a shadow root with copy, node’s shadow root’s mode, true, node’s shadow root’s serializable, node’s shadow root’s delegates focus, and node’s shadow root’s slot assignment.
3. Set copy’s shadow root’s declarative to node’s shadow root’s declarative.
4. For each child child of node’s shadow root, in tree order: append the result of cloning child with document and the clone children flag set, to copy’s shadow root.
Return copy.

The cloneNode(deep) method steps are:

If this is a shadow root, then throw a "NotSupportedError" DOMException.
Return a clone of this, with the clone children flag set if deep is true.

A node A equals a node B if all of the following conditions are true:

A and B implement the same interfaces.
The following are equal, switching on the interface A implements:

DocumentType

Its name, public ID, and system ID.

Element

Its namespace, namespace prefix, local name, and its attribute list’s size.

Attr

Its namespace, local name, and value.

ProcessingInstruction

Its target and data.

Text

Comment

Its data.

Otherwise

—
If A is an element, each attribute in its attribute list has an attribute that equals an attribute in B’s attribute list.
A and B have the same number of children.
Each child of A equals the child of B at the identical index.

The isEqualNode(otherNode) method steps are to return true if otherNode is non-null and this equals otherNode; otherwise false.

The isSameNode(otherNode) method steps are to return true if otherNode is this; otherwise false.

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; otherwise false.

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 steps are:

If this is other, then return zero.
Let node1 be other and node2 be this.
Let attr1 and attr2 be null.
If node1 is an attribute, then set attr1 to node1 and node1 to attr1’s element.
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.
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.
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.
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.
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 the same tree.
Return DOCUMENT_POSITION_FOLLOWING.

The contains(other) method steps are to return true if other is an inclusive descendant of this; otherwise false (including when other is null).

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

If element’s namespace is namespace and its namespace prefix is non-null, then return its namespace prefix.
If element has an attribute whose namespace prefix is "xmlns" and value is namespace, then return element’s first such attribute’s local name.
If element’s parent element is not null, then return the result of running locate a namespace prefix on that element using namespace.
Return null.

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

Element

If prefix is "xml", then return the XML namespace.
If prefix is "xmlns", then return the XMLNS namespace.
If its namespace is non-null and its namespace prefix is prefix, then return namespace.
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.
If its parent element is null, then return null.
Return the result of running locate a namespace on its parent element using prefix.

Document

If its document element is null, then return null.
Return the result of running locate a namespace on its document element using prefix.

DocumentType

DocumentFragment

Return null.

Attr

If its element is null, then return null.
Return the result of running locate a namespace on its element using prefix.

Otherwise

If its parent element is null, then return null.
Return the result of running locate a namespace on its parent element using prefix.

The lookupPrefix(namespace) method steps are:

If namespace is null or the empty string, then return null.
Switch on the interface this implements:

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; otherwise null.

DocumentType

DocumentFragment

Return null.

Attr

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

Otherwise

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

The lookupNamespaceURI(prefix) method steps are:

If prefix is the empty string, then set it to null.
Return the result of running locate a namespace for this using prefix.

The isDefaultNamespace(namespace) method steps are:

If namespace is the empty string, then set it to null.
Let defaultNamespace be the result of running locate a namespace for this using null.
Return true if defaultNamespace is the same as namespace; otherwise false.

The insertBefore(node, child) method steps are to return the result of pre-inserting node into this before child.

The appendChild(node) method steps are to return the result of appending node to this.

The replaceChild(node, child) method steps are to return the result of replacing child with node within this.

The removeChild(child) method steps are to return the result of pre-removing child from this.

The list of elements with qualified name qualifiedName for a node root is the HTMLCollection returned by the following algorithm:

If qualifiedName is U+002A (*), then return an HTMLCollection rooted at root, whose filter matches only descendant elements.
Otherwise, if root’s node document is an HTML document, return an HTMLCollection rooted at root, whose filter matches the following descendant elements:
- Whose namespace is the HTML namespace and whose qualified name is qualifiedName, in ASCII lowercase.
- Whose namespace is not the HTML namespace and whose qualified name is qualifiedName.
Otherwise, return an HTMLCollection rooted at root, whose filter matches descendant elements whose qualified name is qualifiedName.

When invoked with the same argument, and as long as root’s node document’s type has not changed, the same HTMLCollection object may be returned as returned by an earlier call.

The list of elements with namespace namespace and local name localName for a node root is the HTMLCollection returned by the following algorithm:

If namespace is the empty string, then set it to null.
If both namespace and localName are U+002A (*), then return an HTMLCollection rooted at root, whose filter matches descendant elements.
If namespace is U+002A (*), then return an HTMLCollection rooted at root, whose filter matches descendant elements whose local name is localName.
If localName is U+002A (*), then return an HTMLCollection rooted at root, whose filter matches descendant elements whose namespace is namespace.
Return an HTMLCollection rooted at root, whose filter matches descendant elements whose namespace is namespace and local name is localName.

When invoked with the same arguments, the same HTMLCollection object may be returned as returned by an earlier call.

The list of elements with class names classNames for a node root is the HTMLCollection returned by the following algorithm:

Let classes be the result of running the ordered set parser on classNames.
If classes is the empty set, return an empty HTMLCollection.
Return an HTMLCollection rooted at root, whose filter matches descendant elements that have all their classes in classes.
The comparisons for the classes must be done in an ASCII case-insensitive manner if root’s node document’s mode is "quirks"; otherwise in an identical to manner.

When invoked with the same argument, the same HTMLCollection object may be returned as returned by an earlier call.

4.5. Interface `Document`

[
     Exposed
     =Window
    ]
interface
     
      Document
       : 
     Node
      {
  
     constructor
     ();

  [
     SameObject
     ] readonly
     attribute
     
     DOMImplementation
      
     implementation
     ;
  readonly
     attribute
     
     USVString
      
     URL
     ;
  readonly
     attribute
     
     USVString
      
     documentURI
     ;
  readonly
     attribute
     
     DOMString
      
     compatMode
     ;
  readonly
     attribute
     
     DOMString
      
     characterSet
     ;
  readonly
     attribute
     
     DOMString
      
     charset
     ; // legacy alias of .characterSet
  readonly
     attribute
     
     DOMString
      
     inputEncoding
     ; // legacy alias of .characterSet
  readonly
     attribute
     
     DOMString
      
     contentType
     ;

  readonly
     attribute
     
     DocumentType
     ? 
     doctype
     ;
  readonly
     attribute
     
     Element
     ? 
     documentElement
     ;
  
     HTMLCollection
      
     getElementsByTagName
     (
     DOMString
      
      qualifiedName
      );
  
     HTMLCollection
      
     getElementsByTagNameNS
     (
     DOMString
     ? 
      namespace
      , 
     DOMString
      
      localName
      );
  
     HTMLCollection
      
     getElementsByClassName
     (
     DOMString
      
      classNames
      );

  [
     CEReactions
     , 
     NewObject
     ] 
     Element
      
     createElement
     (
     DOMString
      
      localName
      , optional
     (
     DOMString
      or
     
     ElementCreationOptions
     ) 
      options
       = {});
  [
     CEReactions
     , 
     NewObject
     ] 
     Element
      
     createElementNS
     (
     DOMString
     ? 
      namespace
      , 
     DOMString
      
      qualifiedName
      , optional
     (
     DOMString
      or
     
     ElementCreationOptions
     ) 
      options
       = {});
  [
     NewObject
     ] 
     DocumentFragment
      
     createDocumentFragment
     ();
  [
     NewObject
     ] 
     Text
      
     createTextNode
     (
     DOMString
      
      data
      );
  [
     NewObject
     ] 
     CDATASection
      
     createCDATASection
     (
     DOMString
      
      data
      );
  [
     NewObject
     ] 
     Comment
      
     createComment
     (
     DOMString
      
      data
      );
  [
     NewObject
     ] 
     ProcessingInstruction
      
     createProcessingInstruction
     (
     DOMString
      
      target
      , 
     DOMString
      
      data
      );

  [
     CEReactions
     , 
     NewObject
     ] 
     Node
      
     importNode
     (
     Node
      
      node
      , optional
     
     boolean
      
      deep
       = false
    );
  [
     CEReactions
     ] 
     Node
      
     adoptNode
     (
     Node
      
      node
      );

  [
     NewObject
     ] 
     Attr
      
     createAttribute
     (
     DOMString
      
      localName
      );
  [
     NewObject
     ] 
     Attr
      
     createAttributeNS
     (
     DOMString
     ? 
      namespace
      , 
     DOMString
      
      qualifiedName
      );

  [
     NewObject
     ] 
     Event
      
     createEvent
     (
     DOMString
      
      interface
      ); // legacy

  [
     NewObject
     ] 
     Range
      
     createRange
     ();

  // NodeFilter.SHOW_ALL = 0xFFFFFFFF
  [
     NewObject
     ] 
     NodeIterator
      
     createNodeIterator
     (
     Node
      
      root
      , optional
     
     unsigned
      
     long
      
      whatToShow
       = 0xFFFFFFFF, optional
     
     NodeFilter
     ? 
      filter
       = null
    );
  [
     NewObject
     ] 
     TreeWalker
      
     createTreeWalker
     (
     Node
      
      root
      , optional
     
     unsigned
      
     long
      
      whatToShow
       = 0xFFFFFFFF, optional
     
     NodeFilter
     ? 
      filter
       = null
    );
};

[
     Exposed
     =Window
    ]
interface
     
      XMLDocument
       : 
     Document
      {};

dictionary
     
      ElementCreationOptions
       {
  
     DOMString
      
      is
      ;
};

Document nodes are simply known as documents.

A document’s node document is itself.

Each document has an associated encoding (an encoding), content type (a string), URL (a URL), origin (an origin), type ("xml" or "html"), mode ("no-quirks", "quirks", or "limited-quirks"), and allow declarative shadow roots (a boolean). [ENCODING] [URL] [HTML]

Unless stated otherwise, a document’s encoding is the utf-8 encoding, content type is "application/xml", URL is "about:blank", origin is an opaque origin, type is "xml", mode is "no-quirks", and its allow declarative shadow roots is false.

A document is said to be an XML document if its type is "xml"; otherwise an HTML document. Whether a document is an HTML document or an XML document affects the behavior of certain APIs.

A document is said to be in no-quirks mode if its mode is "no-quirks", quirks mode if its mode is "quirks", and limited-quirks mode if its mode is "limited-quirks".

The mode is only ever changed from the default for documents created by the HTML parser based on the presence, absence, or value of the DOCTYPE string, and by a new browsing context (initial "about:blank"). [HTML]

No-quirks mode was originally known as "standards mode" and limited-quirks mode was once known as "almost standards mode". They have been renamed because their details are now defined by standards. (And because Ian Hickson vetoed their original names on the basis that they are nonsensical.)

A document’s get the parent algorithm, given an event, returns null if event’s type attribute value is "load" or document does not have a browsing context; otherwise the document’s relevant global object.

document = new Document(): Returns a new document.
document . implementation: Returns document’s DOMImplementation object.
document . URL
document . documentURI: Returns document’s URL.
document . compatMode: Returns the string "BackCompat" if document’s mode is "quirks"; otherwise "CSS1Compat".
document . characterSet: Returns document’s encoding.
document . contentType: Returns document’s content type.

The new Document() constructor steps are to set this’s origin to the origin of current global object’s associated Document. [HTML]

Unlike createDocument(), this constructor does not return an XMLDocument object, but a document (Document object).

The implementation getter steps are to return the DOMImplementation object that is associated with this.

The URL and documentURI getter steps are to return this’s URL, serialized.

The compatMode getter steps are to return "BackCompat" if this’s mode is "quirks"; otherwise "CSS1Compat".

The characterSet, charset, and inputEncoding getter steps are to return this’s encoding’s name.

The contentType getter steps are to return this’s content type.

document . doctype

Returns the doctype or null if there is none.

document . documentElement

Returns the document element.

collection = document . getElementsByTagName(qualifiedName)

If qualifiedName is "*" returns an HTMLCollection of all descendant elements.

Otherwise, returns an HTMLCollection of all descendant elements whose qualified name is qualifiedName. (Matches case-insensitively against elements in the HTML namespace within an HTML document.)

collection = document . getElementsByTagNameNS(namespace, localName)

If namespace and localName are "*", returns an HTMLCollection of all descendant elements.

If only namespace is "*", returns an HTMLCollection of all descendant elements whose local name is localName.

If only localName is "*", returns an HTMLCollection of all descendant elements whose namespace is namespace.

Otherwise, returns an HTMLCollection of all descendant elements whose namespace is namespace and local name is localName.

collection = document . getElementsByClassName(classNames)

collection = element . getElementsByClassName(classNames)

Returns an HTMLCollection of the elements in the object on which the method was invoked (a document or an element) that have all the classes given by classNames. The classNames argument is interpreted as a space-separated list of classes.

The doctype getter steps are to return the child of this that is a doctype; otherwise null.

The documentElement getter steps are to return this’s document element.

The getElementsByTagName(qualifiedName) method steps are to return the list of elements with qualified name qualifiedName for this.

Thus, in an HTML document, document . getElementsByTagName ( "FOO" ) will match <FOO> elements that are not in the HTML namespace, and <foo> elements that are in the HTML namespace, but not <FOO> elements that are in the HTML namespace.

The getElementsByTagNameNS(namespace, localName) method steps are to return the list of elements with namespace namespace and local name localName for this.

The getElementsByClassName(classNames) method steps are to return the list of elements with class names classNames for this.

Given the following XHTML fragment:

A call to document . getElementById ( "example" ). getElementsByClassName ( "aaa" ) would return an HTMLCollection with the two paragraphs p1 and p2 in it.

A call to getElementsByClassName ( "ccc bbb" ) would only return one node, however, namely p3. A call to document . getElementById ( "example" ). getElementsByClassName ( "bbb ccc " ) would return the same thing.

A call to getElementsByClassName ( "aaa,bbb" ) would return no nodes; none of the elements above are in the aaa,bbb class.

element = document . createElement(localName [, options])

Returns an element with localName as local name (if document is an HTML document, localName gets lowercased). The element’s namespace is the HTML namespace when document is an HTML document or document’s content type is "application/xhtml+xml"; otherwise null.

If localName does not match the Name production an "InvalidCharacterError" DOMException will be thrown.

When supplied, options’s is can be used to create a customized built-in element.

element = document . createElementNS(namespace, qualifiedName [, options])

Returns an element with namespace namespace. Its namespace prefix will be everything before U+003A (:) in qualifiedName or null. Its local name will be everything after U+003A (:) in qualifiedName or qualifiedName.

If qualifiedName does not match the QName production an "InvalidCharacterError" DOMException will be thrown.

If one of the following conditions is true a "NamespaceError" DOMException will be thrown:

Namespace prefix is not null and namespace is the empty string.
Namespace prefix is "xml" and namespace is not the XML namespace.
qualifiedName or namespace prefix is "xmlns" and namespace is not the XMLNS namespace.
namespace is the XMLNS namespace and neither qualifiedName nor namespace prefix is "xmlns".

When supplied, options’s is can be used to create a customized built-in element.

documentFragment = document . createDocumentFragment()

Returns a DocumentFragment node.

text = document . createTextNode(data)

Returns a Text node whose data is data.

text = document . createCDATASection(data)

Returns a CDATASection node whose data is data.

comment = document . createComment(data)

Returns a Comment node whose data is data.

processingInstruction = document . createProcessingInstruction(target, data)

Returns a ProcessingInstruction node whose target is target and data is data. If target does not match the Name production an "InvalidCharacterError" DOMException will be thrown. If data contains "?>" an "InvalidCharacterError" DOMException will be thrown.

The element interface for any name and namespace is Element, unless stated otherwise.

The HTML Standard will, e.g., define that for html and the HTML namespace, the HTMLHtmlElement interface is used. [HTML]

The createElement(localName, options) method steps are:

If localName does not match the Name production, then throw an "InvalidCharacterError" DOMException.
If this is an HTML document, then set localName to localName in ASCII lowercase.
Let is be null.
If options is a dictionary and options["is"] exists, then set is to it.
Let namespace be the HTML namespace, if this is an HTML document or this’s content type is "application/xhtml+xml"; otherwise null.
Return the result of creating an element given this, localName, namespace, null, is, and with the synchronous custom elements flag set.

The internal createElementNS steps, given document, namespace, qualifiedName, and options, are as follows:

Let namespace, prefix, and localName be the result of passing namespace and qualifiedName to validate and extract.
Let is be null.
If options is a dictionary and options["is"] exists, then set is to it.
Return the result of creating an element given document, localName, namespace, prefix, is, and with the synchronous custom elements flag set.

The createElementNS(namespace, qualifiedName, options) method steps are to return the result of running the internal createElementNS steps, given this, namespace, qualifiedName, and options.

createElement() and createElementNS()'s options parameter is allowed to be a string for web compatibility.

The createDocumentFragment() method steps are to return a new DocumentFragment node whose node document is this.

The createTextNode(data) method steps are to return a new Text node whose data is data and node document is this.

No check is performed that data consists of characters that match the Char production.

The createCDATASection(data) method steps are:

If this is an HTML document, then throw a "NotSupportedError" DOMException.
If data contains the string "]]>", then throw an "InvalidCharacterError" DOMException.
Return a new CDATASection node with its data set to data and node document set to this.

The createComment(data) method steps are to return a new Comment node whose data is data and node document is this.

No check is performed that data consists of characters that match the Char production or that it contains two adjacent hyphens or ends with a hyphen.

The createProcessingInstruction(target, data) method steps are:

If target does not match the Name production, then throw an "InvalidCharacterError" DOMException.
If data contains the string "?>", then throw an "InvalidCharacterError" DOMException.
Return a new ProcessingInstruction node, with target set to target, data set to data, and node document set to this.

No check is performed that target contains "xml" or ":", or that data contains characters that match the Char production.

clone = document . importNode(node [, deep = false])

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

If node is a document or a shadow root, throws a "NotSupportedError" DOMException.

node = document . adoptNode(node)

Moves node from another document and returns it.

If node is a document, throws a "NotSupportedError" DOMException or, if node is a shadow root, throws a "HierarchyRequestError" DOMException.

The importNode(node, deep) method steps are:

If node is a document or shadow root, then throw a "NotSupportedError" DOMException.
Return a clone of node, with this and the clone children flag set if deep is true.

Specifications may define adopting steps for all or some nodes. The algorithm is passed node and oldDocument, as indicated in the adopt algorithm.

To adopt a node into a document, run these steps:

Let oldDocument be node’s node document.
If node’s parent is non-null, then remove node.
If document is not oldDocument, then:
1. For each inclusiveDescendant in node’s shadow-including inclusive descendants:
  1. Set inclusiveDescendant’s node document to document.
  2. If inclusiveDescendant is an element, then set the node document of each attribute in inclusiveDescendant’s attribute list to document.
2. For each inclusiveDescendant in node’s shadow-including inclusive descendants that is custom, enqueue a custom element callback reaction with inclusiveDescendant, callback name "adoptedCallback", and an argument list containing oldDocument and document.
3. For each inclusiveDescendant in node’s shadow-including inclusive descendants, in shadow-including tree order, run the adopting steps with inclusiveDescendant and oldDocument.

The adoptNode(node) method steps are:

If node is a document, then throw a "NotSupportedError" DOMException.
If node is a shadow root, then throw a "HierarchyRequestError" DOMException.
If node is a DocumentFragment node whose host is non-null, then return.
Adopt node into this.
Return node.

The createAttribute(localName) method steps are:

If localName does not match the Name production in XML, then throw an "InvalidCharacterError" DOMException.
If this is an HTML document, then set localName to localName in ASCII lowercase.
Return a new attribute whose local name is localName and node document is this.

The createAttributeNS(namespace, qualifiedName) method steps are:

Let namespace, prefix, and localName be the result of passing namespace and qualifiedName to validate and extract.
Return a new attribute whose namespace is namespace, namespace prefix is prefix, local name is localName, and node document is this.

The createEvent(interface) method steps are:

Let constructor be null.

If interface is an ASCII case-insensitive match for any of the strings in the first column in the following table, then set constructor to the interface in the second column on the same row as the matching string:

String	Interface	Notes
"`beforeunloadevent`"	`BeforeUnloadEvent`	[HTML]
"`compositionevent`"	`CompositionEvent`	[UIEVENTS]
"`customevent`"	`CustomEvent`
"`devicemotionevent`"	`DeviceMotionEvent`	[DEVICE-ORIENTATION]
"`deviceorientationevent`"	`DeviceOrientationEvent`	[DEVICE-ORIENTATION]
"`dragevent`"	`DragEvent`	[HTML]
"`event`"	`Event`
"`events`"	`Event`
"`focusevent`"	`FocusEvent`	[UIEVENTS]
"`hashchangeevent`"	`HashChangeEvent`	[HTML]
"`htmlevents`"	`Event`
"`keyboardevent`"	`KeyboardEvent`	[UIEVENTS]
"`messageevent`"	`MessageEvent`	[HTML]
"`mouseevent`"	`MouseEvent`	[UIEVENTS]
"`mouseevents`"	`MouseEvent`	[UIEVENTS]
"`storageevent`"	`StorageEvent`	[HTML]
"`svgevents`"	`Event`
"`textevent`"	`TextEvent`	[UIEVENTS]
"`touchevent`"	`TouchEvent`	[TOUCH-EVENTS]
"`uievent`"	`UIEvent`	[UIEVENTS]
"`uievents`"	`UIEvent`	[UIEVENTS]

If constructor is null, then throw a "NotSupportedError" DOMException.
If the interface indicated by constructor is not exposed on the relevant global object of this, then throw a "NotSupportedError" DOMException.
Typically user agents disable support for touch events in some configurations, in which case this clause would be triggered for the interface TouchEvent.
Let event be the result of creating an event given constructor.
Initialize event’s type attribute to the empty string.
Initialize event’s timeStamp attribute to the result of calling current high resolution time with this’s relevant global object.
Initialize event’s isTrusted attribute to false.
Unset event’s initialized flag.
Return event.

Event constructors ought to be used instead.

The createRange() method steps are to return a new live range with (this, 0) as its start an end.

The Range() constructor can be used instead.

The createNodeIterator(root, whatToShow, filter) method steps are:

Let iterator be a new NodeIterator object.
Set iterator’s root and iterator’s reference to root.
Set iterator’s pointer before reference to true.
Set iterator’s whatToShow to whatToShow.
Set iterator’s filter to filter.
Return iterator.

The createTreeWalker(root, whatToShow, filter) method steps are:

Let walker be a new TreeWalker object.
Set walker’s root and walker’s current to root.
Set walker’s whatToShow to whatToShow.
Set walker’s filter to filter.
Return walker.

4.5.1. Interface `DOMImplementation`

User agents must create a DOMImplementation object whenever a document is created and associate it with that document.

[
     Exposed
     =Window
    ]
interface
     
      DOMImplementation
       {
  [
     NewObject
     ] 
     DocumentType
      
     createDocumentType
     (
     DOMString
      
      qualifiedName
      , 
     DOMString
      
      publicId
      , 
     DOMString
      
      systemId
      );
  [
     NewObject
     ] 
     XMLDocument
      
     createDocument
     (
     DOMString
     ? 
      namespace
      , [
     LegacyNullToEmptyString
     ] 
     DOMString
      
      qualifiedName
      , optional
     
     DocumentType
     ? 
      doctype
       = null
    );
  [
     NewObject
     ] 
     Document
      
     createHTMLDocument
     (optional
     
     DOMString
      
      title
      );

  
     boolean
      
     hasFeature
     (); // useless; always returns true
};

doctype = document . implementation . createDocumentType(qualifiedName, publicId, systemId): Returns a doctype, with the given qualifiedName, publicId, and systemId. If qualifiedName does not match the Name production, an "InvalidCharacterError" DOMException is thrown, and if it does not match the QName production, a "NamespaceError" DOMException is thrown.
doc = document . implementation . createDocument(namespace, qualifiedName [, doctype = null]): Returns an XMLDocument, with a document element whose local name is qualifiedName and whose namespace is namespace (unless qualifiedName is the empty string), and with doctype, if it is given, as its doctype.
This method throws the same exceptions as the createElementNS() method, when invoked with namespace and qualifiedName.
doc = document . implementation . createHTMLDocument([title]): Returns a document, with a basic tree already constructed including a title element, unless the title argument is omitted.

The createDocumentType(qualifiedName, publicId, systemId) method steps are:

Validate qualifiedName.
Return a new doctype, with qualifiedName as its name, publicId as its public ID, and systemId as its system ID, and with its node document set to the associated document of this.

No check is performed that publicId code points match the PubidChar production or that systemId does not contain both a '"' and a "'".

The createDocument(namespace, qualifiedName, doctype) method steps are:

Let document be a new XMLDocument.
Let element be null.
If qualifiedName is not the empty string, then set element to the result of running the internal createElementNS steps, given document, namespace, qualifiedName, and an empty dictionary.
If doctype is non-null, append doctype to document.
If element is non-null, append element to document.
document’s origin is this’s associated document’s origin.
document’s content type is determined by namespace:

HTML namespace

application/xhtml+xml

SVG namespace

image/svg+xml

Any other namespace

application/xml
Return document.

The createHTMLDocument(title) method steps are:

Let doc be a new document that is an HTML document.
Set doc’s content type to "text/html".
Append a new doctype, with "html" as its name and with its node document set to doc, to doc.
Append the result of creating an element given doc, html, and the HTML namespace, to doc.
Append the result of creating an element given doc, head, and the HTML namespace, to the html element created earlier.
If title is given:
1. Append the result of creating an element given doc, title, and the HTML namespace, to the head element created earlier.
2. Append a new Text node, with its data set to title (which could be the empty string) and its node document set to doc, to the title element created earlier.
Append the result of creating an element given doc, body, and the HTML namespace, to the html element created earlier.
doc’s origin is this’s associated document’s origin.
Return doc.

The hasFeature() method steps are to return true.

hasFeature() originally would report whether the user agent claimed to support a given DOM feature, but experience proved it was not nearly as reliable or granular as simply checking whether the desired objects, attributes, or methods existed. As such, it is no longer to be used, but continues to exist (and simply returns true) so that old pages don’t stop working.

4.6. Interface `DocumentType`

[
     Exposed
     =Window
    ]
interface
     
      DocumentType
       : 
     Node
      {
  readonly
     attribute
     
     DOMString
      
     name
     ;
  readonly
     attribute
     
     DOMString
      
     publicId
     ;
  readonly
     attribute
     
     DOMString
      
     systemId
     ;
};

DocumentType nodes are simply known as doctypes.

Doctypes have an associated name, public ID, and system ID.

When a doctype is created, its name is always given. Unless explicitly given when a doctype is created, its public ID and system ID are the empty string.

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

The publicId getter steps are to return this’s public ID.

The systemId getter steps are to return this’s system ID.

4.7. Interface `DocumentFragment`

[
     Exposed
     =Window
    ]
interface
     
      DocumentFragment
       : 
     Node
      {
  
     constructor
     ();
};

A DocumentFragment node has an associated host (null or an element in a different node tree). It is null unless otherwise stated.

An object A is a host-including inclusive ancestor of an object B, if either A is an inclusive ancestor of B, or if B’s root has a non-null host and A is a host-including inclusive ancestor of B’s root’s host.

The DocumentFragment node’s host concept is useful for HTML’s template element and for shadow roots, and impacts the pre-insert and replace algorithms.

tree = new DocumentFragment(): Returns a new DocumentFragment node.

The new DocumentFragment() constructor steps are to set this’s node document to current global object’s associated Document.

4.8. Interface `ShadowRoot`

[
     Exposed
     =Window
    ]
interface
     
      ShadowRoot
       : 
     DocumentFragment
      {
  readonly
     attribute
     
     ShadowRootMode
      
     mode
     ;
  readonly
     attribute
     
     boolean
      
     delegatesFocus
     ;
  readonly
     attribute
     
     SlotAssignmentMode
      
     slotAssignment
     ;
  readonly
     attribute
     
     boolean
      
     clonable
     ;
  readonly
     attribute
     
     boolean
      
     serializable
     ;
  readonly
     attribute
     
     Element
      
     host
     ;
  attribute
     
     EventHandler
      
     onslotchange
     ;
};

enum
     
      ShadowRootMode
       { 
      "open"
      , 
      "closed"
       };
enum
     
      SlotAssignmentMode
       { 
      "manual"
      , 
      "named"
       };

ShadowRoot nodes are simply known as shadow roots.

Shadow roots have an associated mode ("open" or "closed").

Shadow roots have an associated delegates focus. It is initially set to false.

Shadow roots have an associated available to element internals. It is initially set to false.

Shadow roots have an associated declarative (a boolean). It is initially set to false.

Shadow roots’s associated host is never null.

Shadow roots have an associated slot assignment ("manual" or "named").

Shadow roots have an associated clonable (a boolean). It is initially set to false.

Shadow roots have an associated serializable (a boolean). It is initially set to false.

A shadow root’s get the parent algorithm, given an event, returns null if event’s composed flag is unset and shadow root is the root of event’s path’s first struct’s invocation target; otherwise shadow root’s host.

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

The delegatesFocus getter steps are to return this’s delegates focus.

The slotAssignment getter steps are to return this’s slot assignment.

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

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

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

The onslotchange attribute is an event handler IDL attribute for the onslotchange event handler, whose event handler event type is slotchange.

In shadow-including tree order is shadow-including preorder, depth-first traversal of a node tree. Shadow-including preorder, depth-first traversal of a node tree tree is preorder, depth-first traversal of tree, with for each shadow host encountered in tree, shadow-including preorder, depth-first traversal of that element’s shadow root’s node tree just after it is encountered.

The shadow-including root of an object is its root’s host’s shadow-including root, if the object’s root is a shadow root; otherwise its root.

An object A is a shadow-including descendant of an object B, if A is a descendant of B, or A’s root is a shadow root and A’s root’s host is a shadow-including inclusive descendant of B.

A shadow-including inclusive descendant is an object or one of its shadow-including descendants.

An object A is a shadow-including ancestor of an object B, if and only if B is a shadow-including descendant of A.

A shadow-including inclusive ancestor is an object or one of its shadow-including ancestors.

A node A is closed-shadow-hidden from a node B if all of the following conditions are true:

A’s root is a shadow root.
A’s root is not a shadow-including inclusive ancestor of B.
A’s root is a shadow root whose mode is "closed" or A’s root’s host is closed-shadow-hidden from B.

To retarget an object A against an object B, repeat these steps until they return an object:

If one of the following is true
- A is not a node
- A’s root is not a shadow root
- B is a node and A’s root is a shadow-including inclusive ancestor of B
then return A.
Set A to A’s root’s host.

The retargeting algorithm is used by event dispatch as well as other specifications, such as Fullscreen. [FULLSCREEN]

4.9. Interface `Element`

[
     Exposed
     =Window
    ]
interface
     
      Element
       : 
     Node
      {
  readonly
     attribute
     
     DOMString
     ? 
     namespaceURI
     ;
  readonly
     attribute
     
     DOMString
     ? 
     prefix
     ;
  readonly
     attribute
     
     DOMString
      
     localName
     ;
  readonly
     attribute
     
     DOMString
      
     tagName
     ;

  [
     CEReactions
     ] attribute
     
     DOMString
      
     id
     ;
  [
     CEReactions
     ] attribute
     
     DOMString
      
     className
     ;
  [
     SameObject
     , 
     PutForwards
     =
     value
     ] readonly
     attribute
     
     DOMTokenList
      
     classList
     ;
  [
     CEReactions
     , 
     Unscopable
     ] attribute
     
     DOMString
      
     slot
     ;

  
     boolean
      
     hasAttributes
     ();
  [
     SameObject
     ] readonly
     attribute
     
     NamedNodeMap
      
     attributes
     ;
  
     sequence
     <
     DOMString
     > 
     getAttributeNames
     ();
  
     DOMString
     ? 
     getAttribute
     (
     DOMString
      
      qualifiedName
      );
  
     DOMString
     ? 
     getAttributeNS
     (
     DOMString
     ? 
      namespace
      , 
     DOMString
      
      localName
      );
  [
     CEReactions
     ] 
     undefined
      
     setAttribute
     (
     DOMString
      
      qualifiedName
      , 
     DOMString
      
      value
      );
  [
     CEReactions
     ] 
     undefined
      
     setAttributeNS
     (
     DOMString
     ? 
      namespace
      , 
     DOMString
      
      qualifiedName
      , 
     DOMString
      
      value
      );
  [
     CEReactions
     ] 
     undefined
      
     removeAttribute
     (
     DOMString
      
      qualifiedName
      );
  [
     CEReactions
     ] 
     undefined
      
     removeAttributeNS
     (
     DOMString
     ? 
      namespace
      , 
     DOMString
      
      localName
      );
  [
     CEReactions
     ] 
     boolean
      
     toggleAttribute
     (
     DOMString
      
      qualifiedName
      , optional
     
     boolean
      
      force
      );
  
     boolean
      
     hasAttribute
     (
     DOMString
      
      qualifiedName
      );
  
     boolean
      
     hasAttributeNS
     (
     DOMString
     ? 
      namespace
      , 
     DOMString
      
      localName
      );

  
     Attr
     ? 
     getAttributeNode
     (
     DOMString
      
      qualifiedName
      );
  
     Attr
     ? 
     getAttributeNodeNS
     (
     DOMString
     ? 
      namespace
      , 
     DOMString
      
      localName
      );
  [
     CEReactions
     ] 
     Attr
     ? 
     setAttributeNode
     (
     Attr
      
      attr
      );
  [
     CEReactions
     ] 
     Attr
     ? 
     setAttributeNodeNS
     (
     Attr
      
      attr
      );
  [
     CEReactions
     ] 
     Attr
      
     removeAttributeNode
     (
     Attr
      
      attr
      );

  
     ShadowRoot
      
     attachShadow
     (
     ShadowRootInit
      
      init
      );
  readonly
     attribute
     
     ShadowRoot
     ? 
     shadowRoot
     ;

  
     Element
     ? 
     closest
     (
     DOMString
      
      selectors
      );
  
     boolean
      
     matches
     (
     DOMString
      
      selectors
      );
  
     boolean
      
     webkitMatchesSelector
     (
     DOMString
      
      selectors
      ); // legacy alias of .matches

  
     HTMLCollection
      
     getElementsByTagName
     (
     DOMString
      
      qualifiedName
      );
  
     HTMLCollection
      
     getElementsByTagNameNS
     (
     DOMString
     ? 
      namespace
      , 
     DOMString
      
      localName
      );
  
     HTMLCollection
      
     getElementsByClassName
     (
     DOMString
      
      classNames
      );

  [
     CEReactions
     ] 
     Element
     ? 
     insertAdjacentElement
     (
     DOMString
      
      where
      , 
     Element
      
      element
      ); // legacy
  
     undefined
      
     insertAdjacentText
     (
     DOMString
      
      where
      , 
     DOMString
      
      data
      ); // legacy
};

dictionary
     
      ShadowRootInit
       {
  required
     
     ShadowRootMode
      
      mode
      ;
  
     boolean
      
      delegatesFocus
       = false
    ;
  
     SlotAssignmentMode
      
      slotAssignment
       = "named";
  
     boolean
      
      clonable
       = false
    ;
  
     boolean
      
      serializable
       = false
    ;
};

Element nodes are simply known as elements.

Elements have an associated namespace, namespace prefix, local name, custom element state, custom element definition, is value. When an element is created, all of these values are initialized.

An element’s custom element state is one of "undefined", "failed", "uncustomized", "precustomized", or "custom". An element whose custom element state is "uncustomized" or "custom" is said to be defined. An element whose custom element state is "custom" is said to be custom.

Whether or not an element is defined is used to determine the behavior of the :defined pseudo-class. Whether or not an element is custom is used to determine the behavior of the mutation algorithms. The "failed" and "precustomized" states are used to ensure that if a custom element constructor fails to execute correctly the first time, it is not executed again by an upgrade.

The following code illustrates elements in each of these four states:


      <!DOCTYPE html>
      

      <
      
      script
      
      >
      
  window
      .
      customElements
      .
      define
      (
      
      "sw-rey"
      
      ,
       
      class
       
      extends
       HTMLElement 
      {})
      
  window
      .
      customElements
      .
      define
      (
      
      "sw-finn"
      
      ,
       
      class
       
      extends
       HTMLElement 
      {},
       
      {
       
      extends
      
      :
       
      "p"
       
      })
      
  window
      .
      customElements
      .
      define
      (
      
      "sw-kylo"
      
      ,
       
      class
       
      extends
       HTMLElement 
      {
      
    
      constructor
      
      ()
       
      {
      
      
      // super() intentionally omitted for this example
      
    
      }
      
  
      })
      

      </
      
      script
      
      >
      


      <!-- "undefined" (not defined, not custom) -->
      

      <
      
      sw-han
      
      ></
      
      sw-han
      
      >
      

      <
      
      p
       
      is
      
      =
      
      "sw-luke"
      
      ></
      
      p
      
      >
      

      <
      
      p
       
      is
      
      =
      
      "asdf"
      
      ></
      
      p
      
      >
      


      <!-- "failed" (not defined, not custom) -->
      

      <
      
      sw-kylo
      
      ></
      
      sw-kylo
      
      >
      


      <!-- "uncustomized" (defined, not custom) -->
      

      <
      
      p
      
      ></
      
      p
      
      >
      

      <
      
      asdf
      
      ></
      
      asdf
      
      >
      


      <!-- "custom" (defined, custom) -->
      

      <
      
      sw-rey
      
      ></
      
      sw-rey
      
      >
      

      <
      
      p
       
      is
      
      =
      
      "sw-finn"
      
      ></
      
      p
      
      >

Elements also have an associated shadow root (null or a shadow root). It is null unless otherwise stated. An element is a shadow host if its shadow root is non-null.

An element’s qualified name is its local name if its namespace prefix is null; otherwise its namespace prefix, followed by ":", followed by its local name.

An element’s HTML-uppercased qualified name is the return value of these steps:

Let qualifiedName be this’s qualified name.
If this is in the HTML namespace and its node document is an HTML document, then set qualifiedName to qualifiedName in ASCII uppercase.
Return qualifiedName.

User agents could optimize qualified name and HTML-uppercased qualified name by storing them in internal slots.

To create an element, given a document, localName, namespace, and optional prefix, is, and synchronous custom elements flag, run these steps:

If prefix was not given, let prefix be null.
If is was not given, let is be null.
Let result be null.
Let definition be the result of looking up a custom element definition given document, namespace, localName, and is.
If definition is non-null, and definition’s name is not equal to its local name (i.e., definition represents a customized built-in element), then:
1. Let interface be the element interface for localName and the HTML namespace.
2. Set result to a new element that implements interface, with no attributes, namespace set to the HTML namespace, namespace prefix set to prefix, local name set to localName, custom element state set to "undefined", custom element definition set to null, is value set to is, and node document set to document.
3. If the synchronous custom elements flag is set, then run this step while catching any exceptions:
  1. Upgrade element using definition.
  If this step threw an exception, then:
  1. Report the exception.
  2. Set result’s custom element state to "failed".
4. Otherwise, enqueue a custom element upgrade reaction given result and definition.
Otherwise, if definition is non-null, then:
1. If the synchronous custom elements flag is set, then run these steps while catching any exceptions:
  1. Let C be definition’s constructor.
  2. Set result to the result of constructing C, with no arguments.
  3. Assert: result’s custom element state and custom element definition are initialized.
  4. Assert: result’s namespace is the HTML namespace.
    IDL enforces that result is an HTMLElement object, which all use the HTML namespace.
  5. If result’s attribute list is not empty, then throw a "NotSupportedError" DOMException.
  6. If result has children, then throw a "NotSupportedError" DOMException.
  7. If result’s parent is not null, then throw a "NotSupportedError" DOMException.
  8. If result’s node document is not document, then throw a "NotSupportedError" DOMException.
  9. If result’s local name is not equal to localName, then throw a "NotSupportedError" DOMException.
  10. Set result’s namespace prefix to prefix.
  11. Set result’s is value to null.
  If any of these steps threw an exception, then:
  1. Report the exception.
  2. Set result to a new element that implements the HTMLUnknownElement interface, with no attributes, namespace set to the HTML namespace, namespace prefix set to prefix, local name set to localName, custom element state set to "failed", custom element definition set to null, is value set to null, and node document set to document.
2. Otherwise:
  1. Set result to a new element that implements the HTMLElement interface, with no attributes, namespace set to the HTML namespace, namespace prefix set to prefix, local name set to localName, custom element state set to "undefined", custom element definition set to null, is value set to null, and node document set to document.
  2. Enqueue a custom element upgrade reaction given result and definition.
Otherwise:
1. Let interface be the element interface for localName and namespace.
2. Set result to a new element that implements interface, with no attributes, namespace set to namespace, namespace prefix set to prefix, local name set to localName, custom element state set to "uncustomized", custom element definition set to null, is value set to is, and node document set to document.
3. If namespace is the HTML namespace, and either localName is a valid custom element name or is is non-null, then set result’s custom element state to "undefined".
Return result.

Elements also have an attribute list, which is a list exposed through a NamedNodeMap. Unless explicitly given when an element is created, its attribute list is empty.

An element has an attribute A if its attribute list contains A.

This and other specifications may define attribute change steps for elements. The algorithm is passed element, localName, oldValue, value, and namespace.

To handle attribute changes for an attribute attribute with element, oldValue, and newValue, run these steps:

Queue a mutation record of "attributes" for element with attribute’s local name, attribute’s namespace, oldValue, « », « », null, and null.
If element is custom, then enqueue a custom element callback reaction with element, callback name "attributeChangedCallback", and an argument list containing attribute’s local name, oldValue, newValue, and attribute’s namespace.
Run the attribute change steps with element, attribute’s local name, oldValue, newValue, and attribute’s namespace.

To change an attribute attribute to value, run these steps:

Let oldValue be attribute’s value.
Set attribute’s value to value.
Handle attribute changes for attribute with attribute’s element, oldValue, and value.

To append an attribute attribute to an element element, run these steps:

Append attribute to element’s attribute list.
Set attribute’s element to element.
Handle attribute changes for attribute with element, null, and attribute’s value.

To remove an attribute attribute, run these steps:

Let element be attribute’s element.
Remove attribute from element’s attribute list.
Set attribute’s element to null.
Handle attribute changes for attribute with element, attribute’s value, and null.

To replace an attribute oldAttr with an attribute newAttr, run these steps:

Replace oldAttr by newAttr in oldAttr’s element’s attribute list.
Set newAttr’s element to oldAttr’s element.
Set oldAttr’s element to null.
Handle attribute changes for oldAttr with newAttr’s element, oldAttr’s value, and newAttr’s value.

To get an attribute by name given a string qualifiedName and an element element:

If element is in the HTML namespace and its node document is an HTML document, then set qualifiedName to qualifiedName in ASCII lowercase.
Return the first attribute in element’s attribute list whose qualified name is qualifiedName; otherwise null.

To get an attribute by namespace and local name given null or a string namespace, a string localName, and an element element:

If namespace is the empty string, then set it to null.
Return the attribute in element’s attribute list whose namespace is namespace and local name is localName, if any; otherwise null.

To get an attribute value given an element element, a string localName, and an optional null or string namespace (default null):

Let attr be the result of getting an attribute given namespace, localName, and element.
If attr is null, then return the empty string.
Return attr’s value.

To set an attribute given an attribute attr and an element element:

If attr’s element is neither null nor element, throw an "InUseAttributeError" DOMException.
Let oldAttr be the result of getting an attribute given attr’s namespace, attr’s local name, and element.
If oldAttr is attr, return attr.
If oldAttr is non-null, then replace oldAttr with attr.
Otherwise, append attr to element.
Return oldAttr.

To set an attribute value given an element element, a string localName, a string value, an optional null or string prefix (default null), and an optional null or string namespace (default null):

Let attribute be the result of getting an attribute given namespace, localName, and element.
If attribute is null, create an attribute whose namespace is namespace, namespace prefix is prefix, local name is localName, value is value, and node document is element’s node document, then append this attribute to element, and then return.
Change attribute to value.

To remove an attribute by name given a string qualifiedName and an element element:

Let attr be the result of getting an attribute given qualifiedName and element.
If attr is non-null, then remove attr.
Return attr.

To remove an attribute by namespace and local name given null or a string namespace, a string localName, and an element element:

Let attr be the result of getting an attribute given namespace, localName, and element.
If attr is non-null, then remove attr.
Return attr.

An element can have an associated unique identifier (ID)

Historically elements could have multiple identifiers e.g., by using the HTML id attribute and a DTD. This specification makes ID a concept of the DOM and allows for only one per element, given by an id attribute.

Use these attribute change steps to update an element’s ID:

If localName is id, namespace is null, and value is null or the empty string, then unset element’s ID.
Otherwise, if localName is id, namespace is null, then set element’s ID to value.

While this specification defines requirements for class, id, and slot attributes on any element, it makes no claims as to whether using them is conforming or not.

A node’s parent of type Element is known as its parent element. If the node has a parent of a different type, its parent element is null.

namespace = element . namespaceURI: Returns the namespace.
prefix = element . prefix: Returns the namespace prefix.
localName = element . localName: Returns the local name.
qualifiedName = element . tagName: Returns the HTML-uppercased qualified name.

The namespaceURI getter steps are to return this’s namespace.

The prefix getter steps are to return this’s namespace prefix.

The localName getter steps are to return this’s local name.

The tagName getter steps are to return this’s HTML-uppercased qualified name.

element . id [ = value ]: Returns the value of element’s id content attribute. Can be set to change it.
element . className [ = value ]: Returns the value of element’s class content attribute. Can be set to change it.
element . classList: Allows for manipulation of element’s class content attribute as a set of whitespace-separated tokens through a DOMTokenList object.
element . slot [ = value ]: Returns the value of element’s slot content attribute. Can be set to change it.

IDL attributes that are defined to reflect a string name, must have these getter and setter steps:

getter steps: Return the result of running get an attribute value given this and name.
setter steps: Set an attribute value for this using name and the given value.

The id attribute must reflect "id".

The className attribute must reflect "class".

The classList getter steps are to return a DOMTokenList object whose associated element is this and whose associated attribute’s local name is class. The token set of this particular DOMTokenList object are also known as the element’s classes.

The slot attribute must reflect "slot".

id, class, and slot are effectively superglobal attributes as they can appear on any element, regardless of that element’s namespace.

element . hasAttributes()

Returns true if element has attributes; otherwise false.

element . getAttributeNames()

Returns the qualified names of all element’s attributes. Can contain duplicates.

element . getAttribute(qualifiedName)

Returns element’s first attribute whose qualified name is qualifiedName, and null if there is no such attribute otherwise.

element . getAttributeNS(namespace, localName)

Returns element’s attribute whose namespace is namespace and local name is localName, and null if there is no such attribute otherwise.

element . setAttribute(qualifiedName, value)

Sets the value of element’s first attribute whose qualified name is qualifiedName to value.

element . setAttributeNS(namespace, localName, value)

Sets the value of element’s attribute whose namespace is namespace and local name is localName to value.

element . removeAttribute(qualifiedName)

Removes element’s first attribute whose qualified name is qualifiedName.

element . removeAttributeNS(namespace, localName)

Removes element’s attribute whose namespace is namespace and local name is localName.

element . toggleAttribute(qualifiedName [, force])

If force is not given, "toggles" qualifiedName, removing it if it is present and adding it if it is not present. If force is true, adds qualifiedName. If force is false, removes qualifiedName.

Returns true if qualifiedName is now present; otherwise false.

element . hasAttribute(qualifiedName)

Returns true if element has an attribute whose qualified name is qualifiedName; otherwise false.

element . hasAttributeNS(namespace, localName)

Returns true if element has an attribute whose namespace is namespace and local name is localName.

The hasAttributes() method steps are to return false if this’s attribute list is empty; otherwise true.

The attributes getter steps are to return the associated NamedNodeMap.

The getAttributeNames() method steps are to return the qualified names of the attributes in this’s attribute list, in order; otherwise a new list.

These are not guaranteed to be unique.

The getAttribute(qualifiedName) method steps are:

Let attr be the result of getting an attribute given qualifiedName and this.
If attr is null, return null.
Return attr’s value.

The getAttributeNS(namespace, localName) method steps are:

Let attr be the result of getting an attribute given namespace, localName, and this.
If attr is null, return null.
Return attr’s value.

The setAttribute(qualifiedName, value) method steps are:

If qualifiedName does not match the Name production in XML, then throw an "InvalidCharacterError" DOMException.
If this is in the HTML namespace and its node document is an HTML document, then set qualifiedName to qualifiedName in ASCII lowercase.
Let attribute be the first attribute in this’s attribute list whose qualified name is qualifiedName, and null otherwise.
If attribute is null, create an attribute whose local name is qualifiedName, value is value, and node document is this’s node document, then append this attribute to this, and then return.
Change attribute to value.

The setAttributeNS(namespace, qualifiedName, value) method steps are:

Let namespace, prefix, and localName be the result of passing namespace and qualifiedName to validate and extract.
Set an attribute value for this using localName, value, and also prefix and namespace.

The removeAttribute(qualifiedName) method steps are to remove an attribute given qualifiedName and this, and then return undefined.

The removeAttributeNS(namespace, localName) method steps are to remove an attribute given namespace, localName, and this, and then return undefined.

The hasAttribute(qualifiedName) method steps are:

If this is in the HTML namespace and its node document is an HTML document, then set qualifiedName to qualifiedName in ASCII lowercase.
Return true if this has an attribute whose qualified name is qualifiedName; otherwise false.

The toggleAttribute(qualifiedName, force) method steps are:

If qualifiedName does not match the Name production in XML, then throw an "InvalidCharacterError" DOMException.
If this is in the HTML namespace and its node document is an HTML document, then set qualifiedName to qualifiedName in ASCII lowercase.
Let attribute be the first attribute in this’s attribute list whose qualified name is qualifiedName, and null otherwise.
If attribute is null, then:
1. If force is not given or is true, create an attribute whose local name is qualifiedName, value is the empty string, and node document is this’s node document, then append this attribute to this, and then return true.
2. Return false.
Otherwise, if force is not given or is false, remove an attribute given qualifiedName and this, and then return false.
Return true.

The hasAttributeNS(namespace, localName) method steps are:

If namespace is the empty string, then set it to null.
Return true if this has an attribute whose namespace is namespace and local name is localName; otherwise false.

The getAttributeNode(qualifiedName) method steps are to return the result of getting an attribute given qualifiedName and this.

The getAttributeNodeNS(namespace, localName) method steps are to return the result of getting an attribute given namespace, localName, and this.

The setAttributeNode(attr) and setAttributeNodeNS(attr) methods steps are to return the result of setting an attribute given attr and this.

The removeAttributeNode(attr) method steps are:

If this’s attribute list does not contain attr, then throw a "NotFoundError" DOMException.
Remove attr.
Return attr.

var shadow = element . attachShadow(init): Creates a shadow root for element and returns it.
var shadow = element . shadowRoot: Returns element’s shadow root, if any, and if shadow root’s mode is "open", and null otherwise.

A valid shadow host name is:

a valid custom element name
"article", "aside", "blockquote", "body", "div", "footer", "h1", "h2", "h3", "h4", "h5", "h6", "header", "main", "nav", "p", "section", or "span"

The attachShadow(init) method steps are:

Run attach a shadow root with this, init["mode"], init["clonable"], init["serializable"], init["delegatesFocus"], and init["slotAssignment"].
Return this’s shadow root.

To attach a shadow root, given an element element, a string mode, a boolean clonable, a boolean serializable, a boolean delegatesFocus, and a string slotAssignment:

If element’s namespace is not the HTML namespace, then throw a "NotSupportedError" DOMException.
If element’s local name is not a valid shadow host name, then throw a "NotSupportedError" DOMException.
If element’s local name is a valid custom element name, or element’s is value is non-null, then:
1. Let definition be the result of looking up a custom element definition given element’s node document, its namespace, its local name, and its is value.
2. If definition is not null and definition’s disable shadow is true, then throw a "NotSupportedError" DOMException.
If element is a shadow host, then:
1. Let currentShadowRoot be element’s shadow root.
2. If any of the following are true:
  - currentShadowRoot’s declarative is false; or
  - currentShadowRoot’s mode is not mode,
  then throw a "NotSupportedError" DOMException.
3. Otherwise:
  1. Remove all of currentShadowRoot’s children, in tree order.
  2. Set currentShadowRoot’s declarative to false.
  3. Return.
Let shadow be a new shadow root whose node document is element’s node document, host is element, and mode is mode.
Set shadow’s delegates focus to delegatesFocus.
If element’s custom element state is "precustomized" or "custom", then set shadow’s available to element internals to true.
Set shadow’s slot assignment to slotAssignment.
Set shadow’s declarative to false.
Set shadow’s clonable to clonable.
Set shadow’s serializable to serializable.
Set element’s shadow root to shadow.

The shadowRoot getter steps are:

Let shadow be this’s shadow root.
If shadow is null or its mode is "closed", then return null.
Return shadow.

element . closest(selectors): Returns the first (starting at element) inclusive ancestor that matches selectors, and null otherwise.
element . matches(selectors): Returns true if matching selectors against element’s root yields element; otherwise false.

The closest(selectors) method steps are:

Let s be the result of parse a selector from selectors. [SELECTORS4]
If s is failure, then throw a "SyntaxError" DOMException.
Let elements be this’s inclusive ancestors that are elements, in reverse tree order.
For each element in elements, if match a selector against an element, using s, element, and scoping root this, returns success, return element. [SELECTORS4]
Return null.

The matches(selectors) and webkitMatchesSelector(selectors) method steps are:

Let s be the result of parse a selector from selectors. [SELECTORS4]
If s is failure, then throw a "SyntaxError" DOMException.
If the result of match a selector against an element, using s, this, and scoping root this, returns success, then return true; otherwise, return false. [SELECTORS4]

The getElementsByTagName(qualifiedName) method steps are to return the list of elements with qualified name qualifiedName for this.

The getElementsByTagNameNS(namespace, localName) method steps are to return the list of elements with namespace namespace and local name localName for this.

The getElementsByClassName(classNames) method steps are to return the list of elements with class names classNames for this.

To insert adjacent, given an element element, string where, and a node node, run the steps associated with the first ASCII case-insensitive match for where:

"beforebegin"

If element’s parent is null, return null.

Return the result of pre-inserting node into element’s parent before element.

"afterbegin"

Return the result of pre-inserting node into element before element’s first child.

"beforeend"

Return the result of pre-inserting node into element before null.

"afterend"

If element’s parent is null, return null.

Return the result of pre-inserting node into element’s parent before element’s next sibling.

Otherwise

Throw a "SyntaxError" DOMException.

The insertAdjacentElement(where, element) method steps are to return the result of running insert adjacent, give this, where, and element.

The insertAdjacentText(where, data) method steps are:

Let text be a new Text node whose data is data and node document is this’s node document.
Run insert adjacent, given this, where, and text.

This method returns nothing because it existed before we had a chance to design it.

4.9.1. Interface `NamedNodeMap`

[
     Exposed
     =Window
    ,
 
     LegacyUnenumerableNamedProperties
     ]
interface
     
      NamedNodeMap
       {
  readonly
     attribute
     
     unsigned
      
     long
      
     length
     ;
  getter
     
     Attr
     ? 
     item
     (
     unsigned
      
     long
      
      index
      );
  getter
     
     Attr
     ? 
     getNamedItem
     (
     DOMString
      
      qualifiedName
      );
  
     Attr
     ? 
     getNamedItemNS
     (
     DOMString
     ? 
      namespace
      , 
     DOMString
      
      localName
      );
  [
     CEReactions
     ] 
     Attr
     ? 
     setNamedItem
     (
     Attr
      
      attr
      );
  [
     CEReactions
     ] 
     Attr
     ? 
     setNamedItemNS
     (
     Attr
      
      attr
      );
  [
     CEReactions
     ] 
     Attr
      
     removeNamedItem
     (
     DOMString
      
      qualifiedName
      );
  [
     CEReactions
     ] 
     Attr
      
     removeNamedItemNS
     (
     DOMString
     ? 
      namespace
      , 
     DOMString
      
      localName
      );
};

A NamedNodeMap has an associated element (an element).

A NamedNodeMap object’s attribute list is its element’s attribute list.

A NamedNodeMap object’s supported property indices are the numbers in the range zero to its attribute list’s size minus one, unless the attribute list is empty, in which case there are no supported property indices.

The length getter steps are to return the attribute list’s size.

The item(index) method steps are:

If index is equal to or greater than this’s attribute list’s size, then return null.
Otherwise, return this’s attribute list[index].

A NamedNodeMap object’s supported property names are the return value of running these steps:

Let names be the qualified names of the attributes in this NamedNodeMap object’s attribute list, with duplicates omitted, in order.
If this NamedNodeMap object’s element is in the HTML namespace and its node document is an HTML document, then for each name in names:
1. Let lowercaseName be name, in ASCII lowercase.
2. If lowercaseName is not equal to name, remove name from names.
Return names.

The getNamedItem(qualifiedName) method steps are to return the result of getting an attribute given qualifiedName and element.

The getNamedItemNS(namespace, localName) method steps are to return the result of getting an attribute given namespace, localName, and element.

The setNamedItem(attr) and setNamedItemNS(attr) method steps are to return the result of setting an attribute given attr and element.

The removeNamedItem(qualifiedName) method steps are:

Let attr be the result of removing an attribute given qualifiedName and element.
If attr is null, then throw a "NotFoundError" DOMException.
Return attr.

The removeNamedItemNS(namespace, localName) method steps are:

Let attr be the result of removing an attribute given namespace, localName, and element.
If attr is null, then throw a "NotFoundError" DOMException.
Return attr.

4.9.2. Interface `Attr`

[
     Exposed
     =Window
    ]
interface
     
      Attr
       : 
     Node
      {
  readonly
     attribute
     
     DOMString
     ? 
     namespaceURI
     ;
  readonly
     attribute
     
     DOMString
     ? 
     prefix
     ;
  readonly
     attribute
     
     DOMString
      
     localName
     ;
  readonly
     attribute
     
     DOMString
      
     name
     ;
  [
     CEReactions
     ] attribute
     
     DOMString
      
     value
     ;

  readonly
     attribute
     
     Element
     ? 
     ownerElement
     ;

  readonly
     attribute
     
     boolean
      
     specified
     ; // useless; always returns true
};

Attr nodes are simply known as attributes. They are sometimes referred to as content attributes to avoid confusion with IDL attributes.

Attributes have a namespace (null or a non-empty string), namespace prefix (null or a non-empty string), local name (a non-empty string), value (a string), and element (null or an element).

If designed today they would just have a name and value. ☹

An attribute’s qualified name is its local name if its namespace prefix is null, and its namespace prefix, followed by ":", followed by its local name, otherwise.

User agents could have this as an internal slot as an optimization.

When an attribute is created, its local name is given. Unless explicitly given when an attribute is created, its namespace, namespace prefix, and element are set to null, and its value is set to the empty string.

An A attribute is an attribute whose local name is A and whose namespace and namespace prefix are null.

The namespaceURI getter steps are to return this’s namespace.

The prefix getter steps are to return this’s namespace prefix.

The localName getter steps are to return this’s local name.

The name getter steps are to return this’s qualified name.

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

To set an existing attribute value, given an attribute attribute and string value, run these steps:

If attribute’s element is null, then set attribute’s value to value.
Otherwise, change attribute to value.

The value setter steps are to set an existing attribute value with this and the given value.

The ownerElement getter steps are to return this’s element.

The specified getter steps are to return true.

4.10. Interface `CharacterData`

[
     Exposed
     =Window
    ]
interface
     
      CharacterData
       : 
     Node
      {
  attribute
     [
     LegacyNullToEmptyString
     ] 
     DOMString
      
     data
     ;
  readonly
     attribute
     
     unsigned
      
     long
      
     length
     ;
  
     DOMString
      
     substringData
     (
     unsigned
      
     long
      
      offset
      , 
     unsigned
      
     long
      
      count
      );
  
     undefined
      
     appendData
     (
     DOMString
      
      data
      );
  
     undefined
      
     insertData
     (
     unsigned
      
     long
      
      offset
      , 
     DOMString
      
      data
      );
  
     undefined
      
     deleteData
     (
     unsigned
      
     long
      
      offset
      , 
     unsigned
      
     long
      
      count
      );
  
     undefined
      
     replaceData
     (
     unsigned
      
     long
      
      offset
      , 
     unsigned
      
     long
      
      count
      , 
     DOMString
      
      data
      );
};

CharacterData is an abstract interface. You cannot get a direct instance of it. It is used by Text, ProcessingInstruction, and Comment nodes.

Each node inheriting from the CharacterData interface has an associated mutable string called data.

To replace data of node node with offset offset, count count, and data data, run these steps:

Let length be node’s length.
If offset is greater than length, then throw an "IndexSizeError" DOMException.
If offset plus count is greater than length, then set count to length minus offset.
Queue a mutation record of "characterData" for node with null, null, node’s data, « », « », null, and null.
Insert data into node’s data after offset code units.
Let delete offset be offset + data’s length.
Starting from delete offset code units, remove count code units from node’s data.
For each live range whose start node is node and start offset is greater than offset but less than or equal to offset plus count, set its start offset to offset.
For each live range whose end node is node and end offset is greater than offset but less than or equal to offset plus count, set its end offset to offset.
For each live range whose start node is node and start offset is greater than offset plus count, increase its start offset by data’s length and decrease it by count.
For each live range whose end node is node and end offset is greater than offset plus count, increase its end offset by data’s length and decrease it by count.
If node’s parent is non-null, then run the children changed steps for node’s parent.

To substring data with node node, offset offset, and count count, run these steps:

Let length be node’s length.
If offset is greater than length, then throw an "IndexSizeError" DOMException.
If offset plus count is greater than length, return a string whose value is the code units from the offset^th code unit to the end of node’s data, and then return.
Return a string whose value is the code units from the offset^th code unit to the offset+count^th code unit in node’s data.

The data getter steps are to return this’s data. Its setter must replace data with node this, offset 0, count this’s length, and data new value.

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

The substringData(offset, count) method steps are to return the result of running substring data with node this, offset offset, and count count.

The appendData(data) method steps are to replace data with node this, offset this’s length, count 0, and data data.

The insertData(offset, data) method steps are to replace data with node this, offset offset, count 0, and data data.

The deleteData(offset, count) method steps are to replace data with node this, offset offset, count count, and data the empty string.

The replaceData(offset, count, data) method steps are to replace data with node this, offset offset, count count, and data data.

4.11. Interface `Text`

[
     Exposed
     =Window
    ]
interface
     
      Text
       : 
     CharacterData
      {
  
     constructor
     (optional
     
     DOMString
      
      data
       = "");

  [
     NewObject
     ] 
     Text
      
     splitText
     (
     unsigned
      
     long
      
      offset
      );
  readonly
     attribute
     
     DOMString
      
     wholeText
     ;
};

text = new Text([data = ""]): Returns a new Text node whose data is data.
text . splitText(offset): Splits data at the given offset and returns the remainder as Text node.
text . wholeText: Returns the combined data of all direct Text node siblings.

An exclusive Text node is a Text node that is not a CDATASection node.

The contiguous Text nodes of a node node are node, node’s previous sibling Text node, if any, and its contiguous Text nodes, and node’s next sibling Text node, if any, and its contiguous Text nodes, avoiding any duplicates.

The contiguous exclusive Text nodes of a node node are node, node’s previous sibling exclusive Text node, if any, and its contiguous exclusive Text nodes, and node’s next sibling exclusive Text node, if any, and its contiguous exclusive Text nodes, avoiding any duplicates.

The child text content of a node node is the concatenation of the data of all the Text node children of node, in tree order.

The descendant text content of a node node is the concatenation of the data of all the Text node descendants of node, in tree order.

The new Text(data) constructor steps are to set this’s data to data and this’s node document to current global object’s associated Document.

To split a Text node node with offset offset, run these steps:

Let length be node’s length.
If offset is greater than length, then throw an "IndexSizeError" DOMException.
Let count be length minus offset.
Let new data be the result of substringing data with node node, offset offset, and count count.
Let new node be a new Text node, with the same node document as node. Set new node’s data to new data.
Let parent be node’s parent.
If parent is not null, then:
1. Insert new node into parent before node’s next sibling.
2. For each live range whose start node is node and start offset is greater than offset, set its start node to new node and decrease its start offset by offset.
3. For each live range whose end node is node and end offset is greater than offset, set its end node to new node and decrease its end offset by offset.
4. For each live range whose start node is parent and start offset is equal to the index of node plus 1, increase its start offset by 1.
5. For each live range whose end node is parent and end offset is equal to the index of node plus 1, increase its end offset by 1.
Replace data with node node, offset offset, count count, and data the empty string.
Return new node.

The splitText(offset) method steps are to split this with offset offset.

The wholeText getter steps are to return the concatenation of the data of the contiguous Text nodes of this, in tree order.

4.12. Interface `CDATASection`

[
     Exposed
     =Window
    ]
interface
     
      CDATASection
       : 
     Text
      {
};

4.13. Interface `ProcessingInstruction`

[
     Exposed
     =Window
    ]
interface
     
      ProcessingInstruction
       : 
     CharacterData
      {
  readonly
     attribute
     
     DOMString
      
     target
     ;
};

ProcessingInstruction nodes have an associated target.

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

4.14. Interface `Comment`

[
     Exposed
     =Window
    ]
interface
     
      Comment
       : 
     CharacterData
      {
  
     constructor
     (optional
     
     DOMString
      
      data
       = "");
};

comment = new Comment([data = ""]): Returns a new Comment node whose data is data.

The new Comment(data) constructor steps are to set this’s data to data and this’s node document to current global object’s associated Document.

5. Ranges

5.1. Introduction to "DOM Ranges"

StaticRange and Range objects (ranges) represent a sequence of content within a node tree. Each range has a start and an end which are boundary points. A boundary point is a tuple consisting of a node and an offset. So in other words, a range represents a piece of content within a node tree between two boundary points.

Ranges are frequently used in editing for selecting and copying content.

Element: p
- Element: < img src = "insanity-wolf" alt = "Little-endian BOM; decode as big-endian!" >
- Text: CSS 2.1 syndata is
- Element: < em >
  - Text: awesome
- Text: !

In the node tree above, a range can be used to represent the sequence “syndata is awes”. Assuming p is assigned to the p element, and em to the em element, this would be done as follows:


     var
      range 
     =
      
     new
      Range
     (),
     
    firstText 
     =
      p
     .
     childNodes
     [
     
     1
     
     ],
     
    secondText 
     =
      em
     .
     firstChild
range
     .
     setStart
     (
     firstText
     ,
      
     9
     
     )
      
     // do not forget the leading space
     
range
     .
     setEnd
     (
     secondText
     ,
      
     4
     
     )
     

     // range now stringifies to the aforementioned quote

Attributes such as src and alt in the node tree above cannot be represented by a range. Ranges are only useful for nodes.

Range objects, unlike StaticRange objects, are affected by mutations to the node tree. Therefore they are also known as live ranges. Such mutations will not invalidate them and will try to ensure that it still represents the same piece of content. Necessarily, a live range might itself be modified as part of the mutation to the node tree when, e.g., part of the content it represents is mutated.

See the insert and remove algorithms, the normalize() method, and the replace data and split algorithms for details.

Updating live ranges in response to node tree mutations can be expensive. For every node tree change, all affected Range objects need to be updated. Even if the application is uninterested in some live ranges, it still has to pay the cost of keeping them up-to-date when a mutation occurs.

A StaticRange object is a lightweight range that does not update when the node tree mutates. It is therefore not subject to the same maintenance cost as live ranges.

5.2. Boundary points

A boundary point is a tuple consisting of a node (a node) and an offset (a non-negative integer).

A correct boundary point’s offset will be between 0 and the boundary point’s node’s length, inclusive.

The position of a boundary point (nodeA, offsetA) relative to a boundary point (nodeB, offsetB) is before, equal, or after, as returned by these steps:

Assert: nodeA and nodeB have the same root.
If nodeA is nodeB, then return equal if offsetA is offsetB, before if offsetA is less than offsetB, and after if offsetA is greater than offsetB.
If nodeA is following nodeB, then if the position of (nodeB, offsetB) relative to (nodeA, offsetA) is before, return after, and if it is after, return before.
If nodeA is an ancestor of nodeB:
1. Let child be nodeB.
2. While child is not a child of nodeA, set child to its parent.
3. If child’s index is less than offsetA, then return after.
Return before.

5.3. Interface `AbstractRange`

[
     Exposed
     =Window
    ]
interface
     
      AbstractRange
       {
  readonly
     attribute
     
     Node
      
     startContainer
     ;
  readonly
     attribute
     
     unsigned
      
     long
      
     startOffset
     ;
  readonly
     attribute
     
     Node
      
     endContainer
     ;
  readonly
     attribute
     
     unsigned
      
     long
      
     endOffset
     ;
  readonly
     attribute
     
     boolean
      
     collapsed
     ;
};

Objects implementing the AbstractRange interface are known as ranges.

A range has two associated boundary points — a start and end.

For convenience, a range’s start node is its start’s node, its start offset is its start’s offset, its end node is its end’s node, and its end offset is its end’s offset.

A range is collapsed if its start node is its end node and its start offset is its end offset.

node = range . startContainer: Returns range’s start node.
offset = range . startOffset: Returns range’s start offset.
node = range . endContainer: Returns range’s end node.
offset = range . endOffset: Returns range’s end offset.
collapsed = range . collapsed: Returns true if range is collapsed; otherwise false.

The startContainer getter steps are to return this’s start node.

The startOffset getter steps are to return this’s start offset.

The endContainer getter steps are to return this’s end node.

The endOffset getter steps are to return this’s end offset.

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

5.4. Interface `StaticRange`

    dictionary
     
      StaticRangeInit
       {
  required
     
     Node
      
      startContainer
      ;
  required
     
     unsigned
      
     long
      
      startOffset
      ;
  required
     
     Node
      
      endContainer
      ;
  required
     
     unsigned
      
     long
      
      endOffset
      ;
};

[
     Exposed
     =Window
    ]
interface
     
      StaticRange
       : 
     AbstractRange
      {
  
     constructor
     (
     StaticRangeInit
      
      init
      );
};

staticRange = new StaticRange(init): Returns a new range object that does not update when the node tree mutates.

The new StaticRange(init) constructor steps are:

If init["startContainer"] or init["endContainer"] is a DocumentType or Attr node, then throw an "InvalidNodeTypeError" DOMException.
Set this’s start to (init["startContainer"], init["startOffset"]) and end to (init["endContainer"], init["endOffset"]).

A StaticRange is valid if all of the following are true:

Its start and end are in the same node tree.
Its start offset is between 0 and its start node’s length, inclusive.
Its end offset is between 0 and its end node’s length, inclusive.
Its start is before or equal to its end.

5.5. Interface `Range`

[
     Exposed
     =Window
    ]
interface
     
      Range
       : 
     AbstractRange
      {
  
     constructor
     ();

  readonly
     attribute
     
     Node
      
     commonAncestorContainer
     ;

  
     undefined
      
     setStart
     (
     Node
      
      node
      , 
     unsigned
      
     long
      
      offset
      );
  
     undefined
      
     setEnd
     (
     Node
      
      node
      , 
     unsigned
      
     long
      
      offset
      );
  
     undefined
      
     setStartBefore
     (
     Node
      
      node
      );
  
     undefined
      
     setStartAfter
     (
     Node
      
      node
      );
  
     undefined
      
     setEndBefore
     (
     Node
      
      node
      );
  
     undefined
      
     setEndAfter
     (
     Node
      
      node
      );
  
     undefined
      
     collapse
     (optional
     
     boolean
      
      toStart
       = false
    );
  
     undefined
      
     selectNode
     (
     Node
      
      node
      );
  
     undefined
      
     selectNodeContents
     (
     Node
      
      node
      );

  const
     
     unsigned
      
     short
      
      START_TO_START
       = 0;
  const
     
     unsigned
      
     short
      
      START_TO_END
       = 1;
  const
     
     unsigned
      
     short
      
      END_TO_END
       = 2;
  const
     
     unsigned
      
     short
      
      END_TO_START
       = 3;
  
     short
      
     compareBoundaryPoints
     (
     unsigned
      
     short
      
      how
      , 
     Range
      
      sourceRange
      );

  [
     CEReactions
     ] 
     undefined
      
     deleteContents
     ();
  [
     CEReactions
     , 
     NewObject
     ] 
     DocumentFragment
      
     extractContents
     ();
  [
     CEReactions
     , 
     NewObject
     ] 
     DocumentFragment
      
     cloneContents
     ();
  [
     CEReactions
     ] 
     undefined
      
     insertNode
     (
     Node
      
      node
      );
  [
     CEReactions
     ] 
     undefined
      
     surroundContents
     (
     Node
      
      newParent
      );

  [
     NewObject
     ] 
     Range
      
     cloneRange
     ();
  
     undefined
      
     detach
     ();

  
     boolean
      
     isPointInRange
     (
     Node
      
      node
      , 
     unsigned
      
     long
      
      offset
      );
  
     short
      
     comparePoint
     (
     Node
      
      node
      , 
     unsigned
      
     long
      
      offset
      );

  
     boolean
      
     intersectsNode
     (
     Node
      
      node
      );

  
     stringifier
     ;
};

Objects implementing the Range interface are known as live ranges.

Algorithms that modify a tree (in particular the insert, remove, replace data, and split algorithms) modify live ranges associated with that tree.

The root of a live range is the root of its start node.

A node node is contained in a live range range if node’s root is range’s root, and (node, 0) is after range’s start, and (node, node’s length) is before range’s end.

A node is partially contained in a live range if it’s an inclusive ancestor of the live range’s start node but not its end node, or vice versa.

Some facts to better understand these definitions:

The content that one would think of as being within the live range consists of all contained nodes, plus possibly some of the contents of the start node and end node if those are CharacterData nodes.
The nodes that are contained in a live range will generally not be contiguous, because the parent of a contained node will not always be contained.
However, the descendants of a contained node are contained, and if two siblings are contained, so are any siblings that lie between them.
The start node and end node of a live range are never contained within it.
The first contained node (if there are any) will always be after the start node, and the last contained node will always be equal to or before the end node’s last descendant.
There exists a partially contained node if and only if the start node and end node are different.
The commonAncestorContainer attribute value is neither contained nor partially contained.
If the start node is an ancestor of the end node, the common inclusive ancestor will be the start node. Exactly one of its children will be partially contained, and a child will be contained if and only if it precedes the partially contained child. If the end node is an ancestor of the start node, the opposite holds.
If the start node is not an inclusive ancestor of the end node, nor vice versa, the common inclusive ancestor will be distinct from both of them. Exactly two of its children will be partially contained, and a child will be contained if and only if it lies between those two.

range = new Range(): Returns a new live range.

The new Range() constructor steps are to set this’s start and end to (current global object’s associated Document, 0).

container = range . commonAncestorContainer: Returns the node, furthest away from the document, that is an ancestor of both range’s start node and end node.

The commonAncestorContainer getter steps are:

Let container be start node.
While container is not an inclusive ancestor of end node, let container be container’s parent.
Return container.

To set the start or end of a range to a boundary point (node, offset), run these steps:

If node is a doctype, then throw an "InvalidNodeTypeError" DOMException.
If offset is greater than node’s length, then throw an "IndexSizeError" DOMException.
Let bp be the boundary point (node, offset).
If these steps were invoked as "set the start"
1. If range’s root is not equal to node’s root, or if bp is after the range’s end, set range’s end to bp.
2. Set range’s start to bp.
If these steps were invoked as "set the end"
1. If range’s root is not equal to node’s root, or if bp is before the range’s start, set range’s start to bp.
2. Set range’s end to bp.

The setStart(node, offset) method steps are to set the start of this to boundary point (node, offset).

The setEnd(node, offset) method steps are to set the end of this to boundary point (node, offset).

The setStartBefore(node) method steps are:

Let parent be node’s parent.
If parent is null, then throw an "InvalidNodeTypeError" DOMException.
Set the start of this to boundary point (parent, node’s index).

The setStartAfter(node) method steps are:

Let parent be node’s parent.
If parent is null, then throw an "InvalidNodeTypeError" DOMException.
Set the start of this to boundary point (parent, node’s index plus 1).

The setEndBefore(node) method steps are:

Let parent be node’s parent.
If parent is null, then throw an "InvalidNodeTypeError" DOMException.
Set the end of this to boundary point (parent, node’s index).

The setEndAfter(node) method steps are:

Let parent be node’s parent.
If parent is null, then throw an "InvalidNodeTypeError" DOMException.
Set the end of this to boundary point (parent, node’s index plus 1).

The collapse(toStart) method steps are to, if toStart is true, set end to start; otherwise set start to end.

To select a node node within a range range, run these steps:

Let parent be node’s parent.
If parent is null, then throw an "InvalidNodeTypeError" DOMException.
Let index be node’s index.
Set range’s start to boundary point (parent, index).
Set range’s end to boundary point (parent, index plus 1).

The selectNode(node) method steps are to select node within this.

The selectNodeContents(node) method steps are:

If node is a doctype, throw an "InvalidNodeTypeError" DOMException.
Let length be the length of node.
Set start to the boundary point (node, 0).
Set end to the boundary point (node, length).

The compareBoundaryPoints(how, sourceRange) method steps are:

If how is not one of
- START_TO_START,
- START_TO_END,
- END_TO_END, and
- END_TO_START,
then throw a "NotSupportedError" DOMException.
If this’s root is not the same as sourceRange’s root, then throw a "WrongDocumentError" DOMException.
If how is:

START_TO_START:

Let this point be this’s start. Let other point be sourceRange’s start.

START_TO_END:

Let this point be this’s end. Let other point be sourceRange’s start.

END_TO_END:

Let this point be this’s end. Let other point be sourceRange’s end.

END_TO_START:

Let this point be this’s start. Let other point be sourceRange’s end.
If the position of this point relative to other point is

before

Return −1.

equal

Return 0.

after

Return 1.

The deleteContents() method steps are:

If this is collapsed, then return.
Let original start node, original start offset, original end node, and original end offset be this’s start node, start offset, end node, and end offset, respectively.
If original start node is original end node and it is a CharacterData node, then replace data with node original start node, offset original start offset, count original end offset minus original start offset, and data the empty string, and then return.
Let nodes to remove be a list of all the nodes that are contained in this, in tree order, omitting any node whose parent is also contained in this.
If original start node is an inclusive ancestor of original end node, set new node to original start node and new offset to original start offset.
Otherwise:
1. Let reference node equal original start node.
2. While reference node’s parent is not null and is not an inclusive ancestor of original end node, set reference node to its parent.
3. Set new node to the parent of reference node, and new offset to one plus the index of reference node.
  If reference node’s parent were null, it would be the root of this, so would be an inclusive ancestor of original end node, and we could not reach this point.
If original start node is a CharacterData node, then replace data with node original start node, offset original start offset, count original start node’s length − original start offset, data the empty string.
For each node in nodes to remove, in tree order, remove node.
If original end node is a CharacterData node, then replace data with node original end node, offset 0, count original end offset and data the empty string.
Set start and end to (new node, new offset).

To extract a live range range, run these steps:

Let fragment be a new DocumentFragment node whose node document is range’s start node’s node document.
If range is collapsed, then return fragment.
Let original start node, original start offset, original end node, and original end offset be range’s start node, start offset, end node, and end offset, respectively.
If original start node is original end node and it is a CharacterData node, then:
1. Let clone be a clone of original start node.
2. Set the data of clone to the result of substringing data with node original start node, offset original start offset, and count original end offset minus original start offset.
3. Append clone to fragment.
4. Replace data with node original start node, offset original start offset, count original end offset minus original start offset, and data the empty string.
5. Return fragment.
Let common ancestor be original start node.
While common ancestor is not an inclusive ancestor of original end node, set common ancestor to its own parent.
Let first partially contained child be null.
If original start node is not an inclusive ancestor of original end node, set first partially contained child to the first child of common ancestor that is partially contained in range.
Let last partially contained child be null.
If original end node is not an inclusive ancestor of original start node, set last partially contained child to the last child of common ancestor that is partially contained in range.
These variable assignments do actually always make sense. For instance, if original start node is not an inclusive ancestor of original end node, original start node is itself partially contained in range, and so are all its ancestors up until a child of common ancestor. common ancestor cannot be original start node, because it has to be an inclusive ancestor of original end node. The other case is similar. Also, notice that the two children will never be equal if both are defined.
Let contained children be a list of all children of common ancestor that are contained in range, in tree order.
If any member of contained children is a doctype, then throw a "HierarchyRequestError" DOMException.
We do not have to worry about the first or last partially contained node, because a doctype can never be partially contained. It cannot be a boundary point of a range, and it cannot be the ancestor of anything.
If original start node is an inclusive ancestor of original end node, set new node to original start node and new offset to original start offset.
Otherwise:
1. Let reference node equal original start node.
2. While reference node’s parent is not null and is not an inclusive ancestor of original end node, set reference node to its parent.
3. Set new node to the parent of reference node, and new offset to one plus reference node’s index.
  If reference node’s parent is null, it would be the root of range, so would be an inclusive ancestor of original end node, and we could not reach this point.
If first partially contained child is a CharacterData node, then:
In this case, first partially contained child is original start node.
1. Let clone be a clone of original start node.
2. Set the data of clone to the result of substringing data with node original start node, offset original start offset, and count original start node’s length − original start offset.
3. Append clone to fragment.
4. Replace data with node original start node, offset original start offset, count original start node’s length − original start offset, and data the empty string.
Otherwise, if first partially contained child is not null:
1. Let clone be a clone of first partially contained child.
2. Append clone to fragment.
3. Let subrange be a new live range whose start is (original start node, original start offset) and whose end is (first partially contained child, first partially contained child’s length).
4. Let subfragment be the result of extracting subrange.
5. Append subfragment to clone.
For each contained child in contained children, append contained child to fragment.
If last partially contained child is a CharacterData node, then:
In this case, last partially contained child is original end node.
1. Let clone be a clone of original end node.
2. Set the data of clone to the result of substringing data with node original end node, offset 0, and count original end offset.
3. Append clone to fragment.
4. Replace data with node original end node, offset 0, count original end offset, and data the empty string.
Otherwise, if last partially contained child is not null:
1. Let clone be a clone of last partially contained child.
2. Append clone to fragment.
3. Let subrange be a new live range whose start is (last partially contained child, 0) and whose end is (original end node, original end offset).
4. Let subfragment be the result of extracting subrange.
5. Append subfragment to clone.
Set range’s start and end to (new node, new offset).
Return fragment.

The extractContents() method steps are to return the result of extracting this.

To clone the contents of a live range range, run these steps:

Let fragment be a new DocumentFragment node whose node document is range’s start node’s node document.
If range is collapsed, then return fragment.
Let original start node, original start offset, original end node, and original end offset be range’s start node, start offset, end node, and end offset, respectively.
If original start node is original end node and it is a CharacterData node, then:
1. Let clone be a clone of original start node.
2. Set the data of clone to the result of substringing data with node original start node, offset original start offset, and count original end offset minus original start offset.
3. Append clone to fragment.
4. Return fragment.
Let common ancestor be original start node.
While common ancestor is not an inclusive ancestor of original end node, set common ancestor to its own parent.
Let first partially contained child be null.
If original start node is not an inclusive ancestor of original end node, set first partially contained child to the first child of common ancestor that is partially contained in range.
Let last partially contained child be null.
If original end node is not an inclusive ancestor of original start node, set last partially contained child to the last child of common ancestor that is partially contained in range.
These variable assignments do actually always make sense. For instance, if original start node is not an inclusive ancestor of original end node, original start node is itself partially contained in range, and so are all its ancestors up until a child of common ancestor. common ancestor cannot be original start node, because it has to be an inclusive ancestor of original end node. The other case is similar. Also, notice that the two children will never be equal if both are defined.
Let contained children be a list of all children of common ancestor that are contained in range, in tree order.
If any member of contained children is a doctype, then throw a "HierarchyRequestError" DOMException.
We do not have to worry about the first or last partially contained node, because a doctype can never be partially contained. It cannot be a boundary point of a range, and it cannot be the ancestor of anything.
If first partially contained child is a CharacterData node, then:
In this case, first partially contained child is original start node.
1. Let clone be a clone of original start node.
2. Set the data of clone to the result of substringing data with node original start node, offset original start offset, and count original start node’s length − original start offset.
3. Append clone to fragment.
Otherwise, if first partially contained child is not null:
1. Let clone be a clone of first partially contained child.
2. Append clone to fragment.
3. Let subrange be a new live range whose start is (original start node, original start offset) and whose end is (first partially contained child, first partially contained child’s length).
4. Let subfragment be the result of cloning the contents of subrange.
5. Append subfragment to clone.
For each contained child in contained children:
1. Let clone be a clone of contained child with the clone children flag set.
2. Append clone to fragment.
If last partially contained child is a CharacterData node, then:
In this case, last partially contained child is original end node.
1. Let clone be a clone of original end node.
2. Set the data of clone to the result of substringing data with node original end node, offset 0, and count original end offset.
3. Append clone to fragment.
Otherwise, if last partially contained child is not null:
1. Let clone be a clone of last partially contained child.
2. Append clone to fragment.
3. Let subrange be a new live range whose start is (last partially contained child, 0) and whose end is (original end node, original end offset).
4. Let subfragment be the result of cloning the contents of subrange.
5. Append subfragment to clone.
Return fragment.

The cloneContents() method steps are to return the result of cloning the contents of this.

To insert a node node into a live range range, run these steps:

If range’s start node is a ProcessingInstruction or Comment node, is a Text node whose parent is null, or is node, then throw a "HierarchyRequestError" DOMException.
Let referenceNode be null.
If range’s start node is a Text node, set referenceNode to that Text node.
Otherwise, set referenceNode to the child of start node whose index is start offset, and null if there is no such child.
Let parent be range’s start node if referenceNode is null, and referenceNode’s parent otherwise.
Ensure pre-insertion validity of node into parent before referenceNode.
If range’s start node is a Text node, set referenceNode to the result of splitting it with offset range’s start offset.
If node is referenceNode, set referenceNode to its next sibling.
If node’s parent is non-null, then remove node.
Let newOffset be parent’s length if referenceNode is null; otherwise referenceNode’s index.
Increase newOffset by node’s length if node is a DocumentFragment node; otherwise 1.
Pre-insert node into parent before referenceNode.
If range is collapsed, then set range’s end to (parent, newOffset).

The insertNode(node) method steps are to insert node into this.

The surroundContents(newParent) method steps are:

If a non-Text node is partially contained in this, then throw an "InvalidStateError" DOMException.
If newParent is a Document, DocumentType, or DocumentFragment node, then throw an "InvalidNodeTypeError" DOMException.
For historical reasons CharacterData nodes are not checked here and end up throwing later on as a side effect.
Let fragment be the result of extracting this.
If newParent has children, then replace all with null within newParent.
Insert newParent into this.
Append fragment to newParent.
Select newParent within this.

The cloneRange() method steps are to return a new live range with the same start and end as this.

The detach() method steps are to do nothing. Its functionality (disabling a Range object) was removed, but the method itself is preserved for compatibility.

position = range . comparePoint(node, offset): Returns −1 if the point is before the range, 0 if the point is in the range, and 1 if the point is after the range.
intersects = range . intersectsNode(node): Returns whether range intersects node.

The isPointInRange(node, offset) method steps are:

If node’s root is different from this’s root, return false.
If node is a doctype, then throw an "InvalidNodeTypeError" DOMException.
If offset is greater than node’s length, then throw an "IndexSizeError" DOMException.
If (node, offset) is before start or after end, return false.
Return true.

The comparePoint(node, offset) method steps are:

If node’s root is different from this’s root, then throw a "WrongDocumentError" DOMException.
If node is a doctype, then throw an "InvalidNodeTypeError" DOMException.
If offset is greater than node’s length, then throw an "IndexSizeError" DOMException.
If (node, offset) is before start, return −1.
If (node, offset) is after end, return 1.
Return 0.

The intersectsNode(node) method steps are:

If node’s root is different from this’s root, return false.
Let parent be node’s parent.
If parent is null, return true.
Let offset be node’s index.
If (parent, offset) is before end and (parent, offset plus 1) is after start, return true.
Return false.

The stringification behavior must run these steps:

Let s be the empty string.
If this’s start node is this’s end node and it is a Text node, then return the substring of that Text node’s data beginning at this’s start offset and ending at this’s end offset.
If this’s start node is a Text node, then append the substring of that node’s data from this’s start offset until the end to s.
Append the concatenation of the data of all Text nodes that are contained in this, in tree order, to s.
If this’s end node is a Text node, then append the substring of that node’s data from its start until this’s end offset to s.
Return s.

The createContextualFragment(), getClientRects(), and getBoundingClientRect() methods are defined in other specifications. [DOM-Parsing] [CSSOM-VIEW]

6. Traversal

NodeIterator and TreeWalker objects can be used to filter and traverse node trees.

Each NodeIterator and TreeWalker object has an associated active flag to avoid recursive invocations. It is initially unset.

Each NodeIterator and TreeWalker object also has an associated root (a node), a whatToShow (a bitmask), and a filter (a callback).

To filter a node node within a NodeIterator or TreeWalker object traverser, run these steps:

If traverser’s active flag is set, then throw an "InvalidStateError" DOMException.
Let n be node’s nodeType attribute value − 1.
If the n^th bit (where 0 is the least significant bit) of traverser’s whatToShow is not set, then return FILTER_SKIP.
If traverser’s filter is null, then return FILTER_ACCEPT.
Set traverser’s active flag.
Let result be the return value of call a user object’s operation with traverser’s filter, "acceptNode", and « node ». If this throws an exception, then unset traverser’s active flag and rethrow the exception.
Unset traverser’s active flag.
Return result.

6.1. Interface `NodeIterator`

[
     Exposed
     =Window
    ]
interface
     
      NodeIterator
       {
  [
     SameObject
     ] readonly
     attribute
     
     Node
      
     root
     ;
  readonly
     attribute
     
     Node
      
     referenceNode
     ;
  readonly
     attribute
     
     boolean
      
     pointerBeforeReferenceNode
     ;
  readonly
     attribute
     
     unsigned
      
     long
      
     whatToShow
     ;
  readonly
     attribute
     
     NodeFilter
     ? 
     filter
     ;

  
     Node
     ? 
     nextNode
     ();
  
     Node
     ? 
     previousNode
     ();

  
     undefined
      
     detach
     ();
};

NodeIterator objects can be created using the createNodeIterator() method on Document objects.

Each NodeIterator object has an associated iterator collection, which is a collection rooted at the NodeIterator object’s root, whose filter matches any node.

Each NodeIterator object also has an associated reference (a node) and pointer before reference (a boolean).

As mentioned earlier, NodeIterator objects have an associated active flag, root, whatToShow, and filter as well.

The NodeIterator pre-removing steps given a nodeIterator and toBeRemovedNode, are as follows:

If toBeRemovedNode is not an inclusive ancestor of nodeIterator’s reference, or toBeRemovedNode is nodeIterator’s root, then return.
If nodeIterator’s pointer before reference is true, then:
1. Let next be toBeRemovedNode’s first following node that is an inclusive descendant of nodeIterator’s root and is not an inclusive descendant of toBeRemovedNode, and null if there is no such node.
2. If next is non-null, then set nodeIterator’s reference to next and return.
3. Otherwise, set nodeIterator’s pointer before reference to false.
  Steps are not terminated here.
Set nodeIterator’s reference to toBeRemovedNode’s parent, if toBeRemovedNode’s previous sibling is null, and to the inclusive descendant of toBeRemovedNode’s previous sibling that appears last in tree order otherwise.

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

The referenceNode getter steps are to return this’s reference.

The pointerBeforeReferenceNode getter steps are to return this’s pointer before reference.

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

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

To traverse, given a NodeIterator object iterator and a direction direction, run these steps:

Let node be iterator’s reference.
Let beforeNode be iterator’s pointer before reference.
While true:
1. Branch on direction:
  
  next
  
  If beforeNode is false, then set node to the first node following node in iterator’s iterator collection. If there is no such node, then return null.
  
  If beforeNode is true, then set it to false.
  
  previous
  
  If beforeNode is true, then set node to the first node preceding node in iterator’s iterator collection. If there is no such node, then return null.
  
  If beforeNode is false, then set it to true.
2. Let result be the result of filtering node within iterator.
3. If result is FILTER_ACCEPT, then break.
Set iterator’s reference to node.
Set iterator’s pointer before reference to beforeNode.
Return node.

The nextNode() method steps are to return the result of traversing with this and next.

The previousNode() method steps are to return the result of traversing with this and previous.

The detach() method steps are to do nothing. Its functionality (disabling a NodeIterator object) was removed, but the method itself is preserved for compatibility.

6.2. Interface `TreeWalker`

[
     Exposed
     =Window
    ]
interface
     
      TreeWalker
       {
  [
     SameObject
     ] readonly
     attribute
     
     Node
      
     root
     ;
  readonly
     attribute
     
     unsigned
      
     long
      
     whatToShow
     ;
  readonly
     attribute
     
     NodeFilter
     ? 
     filter
     ;
           attribute
     
     Node
      
     currentNode
     ;

  
     Node
     ? 
     parentNode
     ();
  
     Node
     ? 
     firstChild
     ();
  
     Node
     ? 
     lastChild
     ();
  
     Node
     ? 
     previousSibling
     ();
  
     Node
     ? 
     nextSibling
     ();
  
     Node
     ? 
     previousNode
     ();
  
     Node
     ? 
     nextNode
     ();
};

TreeWalker objects can be created using the createTreeWalker() method on Document objects.

Each TreeWalker object has an associated current (a node).

As mentioned earlier TreeWalker objects have an associated root, whatToShow, and filter as well.

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

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

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

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

The currentNode setter steps are to set this’s current to the given value.

The parentNode() method steps are:

Let node be this’s current.
While node is non-null and is not this’s root:
1. Set node to node’s parent.
2. If node is non-null and filtering node within this returns FILTER_ACCEPT, then set this’s current to node and return node.
Return null.

To traverse children, given a walker and type, run these steps:

Let node be walker’s current.
Set node to node’s first child if type is first, and node’s last child if type is last.
While node is non-null:
1. Let result be the result of filtering node within walker.
2. If result is FILTER_ACCEPT, then set walker’s current to node and return node.
3. If result is FILTER_SKIP, then:
  1. Let child be node’s first child if type is first, and node’s last child if type is last.
  2. If child is non-null, then set node to child and continue.
4. While node is non-null:
  1. Let sibling be node’s next sibling if type is first, and node’s previous sibling if type is last.
  2. If sibling is non-null, then set node to sibling and break.
  3. Let parent be node’s parent.
  4. If parent is null, walker’s root, or walker’s current, then return null.
  5. Set node to parent.
Return null.

The firstChild() method steps are to traverse children with this and first.

The lastChild() method steps are to traverse children with this and last.

To traverse siblings, given a walker and type, run these steps:

Let node be walker’s current.
If node is root, then return null.
While true:
1. Let sibling be node’s next sibling if type is next, and node’s previous sibling if type is previous.
2. While sibling is non-null:
  1. Set node to sibling.
  2. Let result be the result of filtering node within walker.
  3. If result is FILTER_ACCEPT, then set walker’s current to node and return node.
  4. Set sibling to node’s first child if type is next, and node’s last child if type is previous.
  5. If result is FILTER_REJECT or sibling is null, then set sibling to node’s next sibling if type is next, and node’s previous sibling if type is previous.
3. Set node to node’s parent.
4. If node is null or walker’s root, then return null.
5. If the return value of filtering node within walker is FILTER_ACCEPT, then return null.

The nextSibling() method steps are to traverse siblings with this and next.

The previousSibling() method steps are to traverse siblings with this and previous.

The previousNode() method steps are:

Let node be this’s current.
While node is not this’s root:
1. Let sibling be node’s previous sibling.
2. While sibling is non-null:
  1. Set node to sibling.
  2. Let result be the result of filtering node within this.
  3. While result is not FILTER_REJECT and node has a child:
    1. Set node to node’s last child.
    2. Set result to the result of filtering node within this.
  4. If result is FILTER_ACCEPT, then set this’s current to node and return node.
  5. Set sibling to node’s previous sibling.
3. If node is this’s root or node’s parent is null, then return null.
4. Set node to node’s parent.
5. If the return value of filtering node within this is FILTER_ACCEPT, then set this’s current to node and return node.
Return null.

The nextNode() method steps are:

Let node be this’s current.
Let result be FILTER_ACCEPT.
While true:
1. While result is not FILTER_REJECT and node has a child:
  1. Set node to its first child.
  2. Set result to the result of filtering node within this.
  3. If result is FILTER_ACCEPT, then set this’s current to node and return node.
2. Let sibling be null.
3. Let temporary be node.
4. While temporary is non-null:
  1. If temporary is this’s root, then return null.
  2. Set sibling to temporary’s next sibling.
  3. If sibling is non-null, then set node to sibling and break.
  4. Set temporary to temporary’s parent.
5. Set result to the result of filtering node within this.
6. If result is FILTER_ACCEPT, then set this’s current to node and return node.

6.3. Interface `NodeFilter`

[
     Exposed
     =Window
    ]
callback
     interface
     
      NodeFilter
       {
  // Constants for acceptNode()
  const
     
     unsigned
      
     short
      
     FILTER_ACCEPT
      = 1;
  const
     
     unsigned
      
     short
      
     FILTER_REJECT
      = 2;
  const
     
     unsigned
      
     short
      
     FILTER_SKIP
      = 3;

  // Constants for whatToShow
  const
     
     unsigned
      
     long
      
     SHOW_ALL
      = 0xFFFFFFFF;
  const
     
     unsigned
      
     long
      
     SHOW_ELEMENT
      = 0x1;
  const
     
     unsigned
      
     long
      
     SHOW_ATTRIBUTE
      = 0x2;
  const
     
     unsigned
      
     long
      
     SHOW_TEXT
      = 0x4;
  const
     
     unsigned
      
     long
      
     SHOW_CDATA_SECTION
      = 0x8;
  const
     
     unsigned
      
     long
      
      SHOW_ENTITY_REFERENCE
       = 0x10; // legacy
  const
     
     unsigned
      
     long
      
      SHOW_ENTITY
       = 0x20; // legacy
  const
     
     unsigned
      
     long
      
     SHOW_PROCESSING_INSTRUCTION
      = 0x40;
  const
     
     unsigned
      
     long
      
     SHOW_COMMENT
      = 0x80;
  const
     
     unsigned
      
     long
      
     SHOW_DOCUMENT
      = 0x100;
  const
     
     unsigned
      
     long
      
     SHOW_DOCUMENT_TYPE
      = 0x200;
  const
     
     unsigned
      
     long
      
     SHOW_DOCUMENT_FRAGMENT
      = 0x400;
  const
     
     unsigned
      
     long
      
      SHOW_NOTATION
       = 0x800; // legacy

  
     unsigned
      
     short
      
      acceptNode
      (
     Node
      
      node
      );
};

NodeFilter objects can be used as filter for NodeIterator and TreeWalker objects and also provide constants for their whatToShow bitmask. A NodeFilter object is typically implemented as a JavaScript function.

These constants can be used as filter return value:

FILTER_ACCEPT (1);
FILTER_REJECT (2);
FILTER_SKIP (3).

These constants can be used for whatToShow:

SHOW_ALL (4294967295, FFFFFFFF in hexadecimal);
SHOW_ELEMENT (1);
SHOW_ATTRIBUTE (2);
SHOW_TEXT (4);
SHOW_CDATA_SECTION (8);
SHOW_PROCESSING_INSTRUCTION (64, 40 in hexadecimal);
SHOW_COMMENT (128, 80 in hexadecimal);
SHOW_DOCUMENT (256, 100 in hexadecimal);
SHOW_DOCUMENT_TYPE (512, 200 in hexadecimal);
SHOW_DOCUMENT_FRAGMENT (1024, 400 in hexadecimal).

7. Sets

Yes, the name DOMTokenList is an unfortunate legacy mishap.

7.1. Interface `DOMTokenList`

[
     Exposed
     =Window
    ]
interface
     
      DOMTokenList
       {
  readonly
     attribute
     
     unsigned
      
     long
      
     length
     ;
  getter
     
     DOMString
     ? 
     item
     (
     unsigned
      
     long
      
      index
      );
  
     boolean
      
     contains
     (
     DOMString
      
      token
      );
  [
     CEReactions
     ] 
     undefined
      
     add
     (
     DOMString
     ... 
      tokens
      );
  [
     CEReactions
     ] 
     undefined
      
     remove
     (
     DOMString
     ... 
      tokens
      );
  [
     CEReactions
     ] 
     boolean
      
     toggle
     (
     DOMString
      
      token
      , optional
     
     boolean
      
      force
      );
  [
     CEReactions
     ] 
     boolean
      
     replace
     (
     DOMString
      
      token
      , 
     DOMString
      
      newToken
      );
  
     boolean
      
     supports
     (
     DOMString
      
      token
      );
  [
     CEReactions
     ] 
     stringifier
      attribute
     
     DOMString
      
     value
     ;
  iterable
    <
     DOMString
     >;
};

A DOMTokenList object has an associated token set (a set), which is initially empty.

A DOMTokenList object also has an associated element and an attribute’s local name.

Specifications may define supported tokens for a DOMTokenList's associated attribute’s local name.

A DOMTokenList object’s validation steps for a given token are:

If the associated attribute’s local name does not define supported tokens, throw a TypeError.
Let lowercase token be a copy of token, in ASCII lowercase.
If lowercase token is present in supported tokens, return true.
Return false.

A DOMTokenList object’s update steps are:

If the associated element does not have an associated attribute and token set is empty, then return.
Set an attribute value for the associated element using associated attribute’s local name and the result of running the ordered set serializer for token set.

A DOMTokenList object’s serialize steps are to return the result of running get an attribute value given the associated element and the associated attribute’s local name.

A DOMTokenList object has these attribute change steps for its associated element:

If localName is associated attribute’s local name, namespace is null, and value is null, then empty token set.
Otherwise, if localName is associated attribute’s local name, namespace is null, then set token set to value, parsed.

When a DOMTokenList object is created, then:

Let element be associated element.
Let localName be associated attribute’s local name.
Let value be the result of getting an attribute value given element and localName.
Run the attribute change steps for element, localName, value, value, and null.

tokenlist . length

Returns the number of tokens.

tokenlist . item(index)

tokenlist[index]

Returns the token with index index.

tokenlist . contains(token)

Returns true if token is present; otherwise false.

tokenlist . add(tokens…)

Adds all arguments passed, except those already present.

Throws a "SyntaxError" DOMException if one of the arguments is the empty string.

Throws an "InvalidCharacterError" DOMException if one of the arguments contains any ASCII whitespace.

tokenlist . remove(tokens…)

Removes arguments passed, if they are present.

Throws a "SyntaxError" DOMException if one of the arguments is the empty string.

Throws an "InvalidCharacterError" DOMException if one of the arguments contains any ASCII whitespace.

tokenlist . toggle(token [, force])

If force is not given, "toggles" token, removing it if it’s present and adding it if it’s not present. If force is true, adds token (same as add()). If force is false, removes token (same as remove()).

Returns true if token is now present; otherwise false.

Throws a "SyntaxError" DOMException if token is empty.

Throws an "InvalidCharacterError" DOMException if token contains any spaces.

tokenlist . replace(token, newToken)

Replaces token with newToken.

Returns true if token was replaced with newToken; otherwise false.

Throws a "SyntaxError" DOMException if one of the arguments is the empty string.

Throws an "InvalidCharacterError" DOMException if one of the arguments contains any ASCII whitespace.

tokenlist . supports(token)

Returns true if token is in the associated attribute’s supported tokens. Returns false otherwise.

Throws a TypeError if the associated attribute has no supported tokens defined.

tokenlist . value

Returns the associated set as string.

Can be set, to change the associated attribute.

The length attribute' getter must return this’s token set’s size.

The object’s supported property indices are the numbers in the range zero to object’s token set’s size minus one, unless token set is empty, in which case there are no supported property indices.

The item(index) method steps are:

If index is equal to or greater than this’s token set’s size, then return null.
Return this’s token set[index].

The contains(token) method steps are to return true if this’s token set[token] exists; otherwise false.

The add(tokens…) method steps are:

For each token in tokens:
1. If token is the empty string, then throw a "SyntaxError" DOMException.
2. If token contains any ASCII whitespace, then throw an "InvalidCharacterError" DOMException.
For each token in tokens, append token to this’s token set.
Run the update steps.

The remove(tokens…) method steps are:

For each token in tokens:
1. If token is the empty string, then throw a "SyntaxError" DOMException.
2. If token contains any ASCII whitespace, then throw an "InvalidCharacterError" DOMException.
For each token in tokens, remove token from this’s token set.
Run the update steps.

The toggle(token, force) method steps are:

If token is the empty string, then throw a "SyntaxError" DOMException.
If token contains any ASCII whitespace, then throw an "InvalidCharacterError" DOMException.
If this’s token set[token] exists, then:
1. If force is either not given or is false, then remove token from this’s token set, run the update steps and return false.
2. Return true.
Otherwise, if force not given or is true, append token to this’s token set, run the update steps, and return true.
Return false.

The update steps are not always run for toggle() for web compatibility.

The replace(token, newToken) method steps are:

If either token or newToken is the empty string, then throw a "SyntaxError" DOMException.
If either token or newToken contains any ASCII whitespace, then throw an "InvalidCharacterError" DOMException.
If this’s token set does not contain token, then return false.
Replace token in this’s token set with newToken.
Run the update steps.
Return true.

The update steps are not always run for replace() for web compatibility.

The supports(token) method steps are:

Let result be the return value of validation steps called with token.
Return result.

The value attribute must return the result of running this’s serialize steps.

Setting the value attribute must set an attribute value for the associated element using associated attribute’s local name and the given value.

8. XPath

DOM Level 3 XPath defined an API for evaluating XPath 1.0 expressions. These APIs are widely implemented, but have not been maintained. The interface definitions are maintained here so that they can be updated when Web IDL changes. Complete definitions of these APIs remain necessary and such work is tracked and can be contributed to in whatwg/dom#67. [DOM-Level-3-XPath] [XPath] [WEBIDL]

8.1. Interface `XPathResult`

[
     Exposed
     =Window
    ]
interface
     
      XPathResult
       {
  const
     
     unsigned
      
     short
      
      ANY_TYPE
       = 0;
  const
     
     unsigned
      
     short
      
      NUMBER_TYPE
       = 1;
  const
     
     unsigned
      
     short
      
      STRING_TYPE
       = 2;
  const
     
     unsigned
      
     short
      
      BOOLEAN_TYPE
       = 3;
  const
     
     unsigned
      
     short
      
      UNORDERED_NODE_ITERATOR_TYPE
       = 4;
  const
     
     unsigned
      
     short
      
      ORDERED_NODE_ITERATOR_TYPE
       = 5;
  const
     
     unsigned
      
     short
      
      UNORDERED_NODE_SNAPSHOT_TYPE
       = 6;
  const
     
     unsigned
      
     short
      
      ORDERED_NODE_SNAPSHOT_TYPE
       = 7;
  const
     
     unsigned
      
     short
      
      ANY_UNORDERED_NODE_TYPE
       = 8;
  const
     
     unsigned
      
     short
      
      FIRST_ORDERED_NODE_TYPE
       = 9;

  readonly
     attribute
     
     unsigned
      
     short
      
      resultType
      ;
  readonly
     attribute
     
     unrestricted
      
     double
      
      numberValue
      ;
  readonly
     attribute
     
     DOMString
      
      stringValue
      ;
  readonly
     attribute
     
     boolean
      
      booleanValue
      ;
  readonly
     attribute
     
     Node
     ? 
      singleNodeValue
      ;
  readonly
     attribute
     
     boolean
      
      invalidIteratorState
      ;
  readonly
     attribute
     
     unsigned
      
     long
      
      snapshotLength
      ;

  
     Node
     ? 
      iterateNext
      ();
  
     Node
     ? 
      snapshotItem
      (
     unsigned
      
     long
      
      index
      );
};

8.2. Interface `XPathExpression`

[
     Exposed
     =Window
    ]
interface
     
      XPathExpression
       {
  // XPathResult.ANY_TYPE = 0
  
     XPathResult
      
      evaluate
      (
     Node
      
      contextNode
      , optional
     
     unsigned
      
     short
      
      type
       = 0, optional
     
     XPathResult
     ? 
      result
       = null
    );
};

8.3. Mixin `XPathEvaluatorBase`

    callback
     interface
     
      XPathNSResolver
       {
  
     DOMString
     ? 
      lookupNamespaceURI
      (
     DOMString
     ? 
      prefix
      );
};

interface
     mixin
     
      XPathEvaluatorBase
       {
  [
     NewObject
     ] 
     XPathExpression
      
      createExpression
      (
     DOMString
      
      expression
      , optional
     
     XPathNSResolver
     ? 
      resolver
       = null
    );
  
     Node
      
     createNSResolver
     (
     Node
      
      nodeResolver
      ); // legacy
  // XPathResult.ANY_TYPE = 0
  
     XPathResult
      
      evaluate
      (
     DOMString
      
      expression
      , 
     Node
      
      contextNode
      , optional
     
     XPathNSResolver
     ? 
      resolver
       = null
    , optional
     
     unsigned
      
     short
      
      type
       = 0, optional
     
     XPathResult
     ? 
      result
       = null
    );
};

     Document
      includes
     
     XPathEvaluatorBase
     ;

The createNSResolver(nodeResolver) method steps are to return nodeResolver.

This method exists only for historical reasons.

8.4. Interface `XPathEvaluator`

[
     Exposed
     =Window
    ]
interface
     
      XPathEvaluator
       {
  
      constructor
      ();
};


     XPathEvaluator
      includes
     
     XPathEvaluatorBase
     ;

For historical reasons you can both construct XPathEvaluator and access the same methods on Document.

9. XSLT

XSL Transformations (XSLT) is a language for transforming XML documents into other XML documents. The APIs defined in this section have been widely implemented, and are maintained here so that they can be updated when Web IDL changes. Complete definitions of these APIs remain necessary and such work is tracked and can be contributed to in whatwg/dom#181. [XSLT]

9.1. Interface `XSLTProcessor`

[
     Exposed
     =Window
    ]
interface
     
      XSLTProcessor
       {
  
      constructor
      ();
  
     undefined
      
      importStylesheet
      (
     Node
      
      style
      );
  [
     CEReactions
     ] 
     DocumentFragment
      
      transformToFragment
      (
     Node
      
      source
      , 
     Document
      
      output
      );
  [
     CEReactions
     ] 
     Document
      
      transformToDocument
      (
     Node
      
      source
      );
  
     undefined
      
      setParameter
      ([
     LegacyNullToEmptyString
     ] 
     DOMString
      
      namespaceURI
      , 
     DOMString
      
      localName
      , 
     any
      
      value
      );
  
     any
      
      getParameter
      ([
     LegacyNullToEmptyString
     ] 
     DOMString
      
      namespaceURI
      , 
     DOMString
      
      localName
      );
  
     undefined
      
      removeParameter
      ([
     LegacyNullToEmptyString
     ] 
     DOMString
      
      namespaceURI
      , 
     DOMString
      
      localName
      );
  
     undefined
      
      clearParameters
      ();
  
     undefined
      
      reset
      ();
};

10. Security and privacy considerations

There are no known security or privacy considerations for this standard.

11. Historical

This standard used to contain several interfaces and interface members that have been removed.

These interfaces have been removed:

DOMConfiguration
DOMError
DOMErrorHandler
DOMImplementationList
DOMImplementationSource
DOMLocator
DOMObject
DOMUserData
Entity
EntityReference
MutationEvent
MutationNameEvent
NameList
Notation
RangeException
TypeInfo
UserDataHandler

And these interface members have been removed:

Attr

schemaTypeInfo
isId

Document

createEntityReference()
xmlEncoding
xmlStandalone
xmlVersion
strictErrorChecking
domConfig
normalizeDocument()
renameNode()

DocumentType

entities
notations
internalSubset

DOMImplementation

getFeature()

Element

schemaTypeInfo
setIdAttribute()
setIdAttributeNS()
setIdAttributeNode()

Node

isSupported
getFeature()
getUserData()
setUserData()

NodeIterator

expandEntityReferences

Text

isElementContentWhitespace
replaceWholeText()

TreeWalker

expandEntityReferences

Acknowledgments

There have been a lot of people that have helped make DOM more interoperable over the years and thereby furthered the goals of this standard. Likewise many people have helped making this standard what it is today.

With that, many thanks to Adam Klein, Adrian Bateman, Ahmid snuggs, Alex Komoroske, Alex Russell, Alexey Shvayka, Andreu Botella, Anthony Ramine, Arkadiusz Michalski, Arnaud Le Hors, Arun Ranganathan, Benjamin Gruenbaum, Björn Höhrmann, Boris Zbarsky, Brandon Payton, Brandon Slade, Brandon Wallace, Brian Kardell, C. Scott Ananian, Cameron McCormack, Chris Dumez, Chris Paris, Chris Rebert, Cyrille Tuzi, Dan Burzo, Daniel Clark, Daniel Glazman, Darin Fisher, David Bruant, David Flanagan, David Håsäther, David Hyatt, Deepak Sherveghar, Dethe Elza, Dimitri Glazkov, Domenic Denicola, Dominic Cooney, Dominique Hazaël-Massieux, Don Jordan, Doug Schepers, Edgar Chen, Elisée Maurer, Elliott Sprehn, Emilio Cobos Álvarez, Eric Bidelman, Erik Arvidsson, François Remy, Gary Kacmarcik, Gavin Nicol, Giorgio Liscio, Glen Huang, Glenn Adams, Glenn Maynard, Hajime Morrita, Harald Alvestrand, Hayato Ito, Henri Sivonen, Hongchan Choi, Hunan Rostomyan, Ian Hickson, Igor Bukanov, Jacob Rossi, Jake Archibald, Jake Verbaten, James Graham, James Greene, James M Snell, James Robinson, Jeffrey Yasskin, Jens Lindström, Jeremy Davis, Jesse McCarthy, Jinho Bang, João Eiras, Joe Kesselman, John Atkins, John Dai, Jonas Sicking, Jonathan Kingston, Jonathan Robie, Joris van der Wel, Joshua Bell, J. S. Choi, Jungkee Song, Justin Summerlin, Kagami Sascha Rosylight, 呂康豪 (Kang-Hao Lu), 田村健人 (Kent TAMURA), Kevin J. Sung, Kevin Sweeney, Kirill Topolyan, Koji Ishii, Lachlan Hunt, Lauren Wood, Luca Casonato, Luke Zielinski, Magne Andersson, Majid Valipour, Malte Ubl, Manish Goregaokar, Manish Tripathi, Marcos Caceres, Mark Miller, Martijn van der Ven, Mason Freed, Mats Palmgren, Mounir Lamouri, Michael Stramel, Michael™ Smith, Mike Champion, Mike Taylor, Mike West, Nicolás Peña Moreno, Nidhi Jaju, Ojan Vafai, Oliver Nightingale, Olli Pettay, Ondřej Žára, Peter Sharpe, Philip Jägenstedt, Philippe Le Hégaret, Piers Wombwell, Pierre-Marie Dartus, prosody—Gab Vereable Context(, Rafael Weinstein, Rakina Zata Amni, Richard Bradshaw, Rick Byers, Rick Waldron, Robbert Broersma, Robin Berjon, Roland Steiner, Rune F. Halvorsen, Russell Bicknell, Ruud Steltenpool, Ryosuke Niwa, Sam Dutton, Sam Sneddon, Samuel Giles, Sanket Joshi, Scott Haseley, Sebastian Mayr, Seo Sanghyeon, Sergey G. Grekhov, Shiki Okasaka, Shinya Kawanaka, Simon Pieters, Stef Busking, Steve Byrne, Stig Halvorsen, Tab Atkins, Takashi Sakamoto, Takayoshi Kochi, Theresa O’Connor, Theodore Dubois, timeless, Timo Tijhof, Tobie Langel, Tom Pixley, Travis Leithead, Trevor Rowbotham, triple-underscore, Tristan Fraipont, Veli Şenol, Vidur Apparao, Warren He, Xidorn Quan, Yash Handa, Yehuda Katz, Yoav Weiss, Yoichi Osato, Yoshinori Sano, Yu Han, Yusuke Abe, and Zack Weinberg for being awesome!

This standard is written by Anne van Kesteren (Apple, annevk@annevk.nl) with substantial contributions from Aryeh Gregor (ayg@aryeh.name) and Ms2ger (ms2ger@gmail.com).

Intellectual property rights

Part of the revision history of the integration points related to custom elements can be found in the w3c/webcomponents repository, which is available under the W3C Software and Document License.

Copyright © WHATWG (Apple, Google, Mozilla, Microsoft). This work is licensed under a Creative Commons Attribution 4.0 International License. To the extent portions of it are incorporated into source code, such portions in the source code are licensed under the BSD 3-Clause License instead.

This is the Living Standard. Those interested in the patent-review version should view the Living Standard Review Draft.

DOM

Abstract

1. Infrastructure

1.1. Trees

1.2. Ordered sets

1.3. Selectors

1.4. Namespaces

2. Events

2.1. Introduction to "DOM Events"

2.2. Interface Event

2.3. Legacy extensions to the Window interface

2.4. Interface CustomEvent

2.5. Constructing events

2.6. Defining event interfaces

2.7. Interface EventTarget

2.8. Observing event listeners

2.9. Dispatching events

2.10. Firing events

2.11. Action versus occurrence

3. Aborting ongoing activities

3.1. Interface AbortController

3.2. Interface AbortSignal

3.2.1. Garbage collection

3.3. Using AbortController and AbortSignal objects in APIs

4. Nodes

4.1. Introduction to "The DOM"

4.2. Node tree

4.2.1. Document tree

4.2.2. Shadow tree

4.2.2.1. Slots

4.2.2.2. Slottables

4.2.2.3. Finding slots and slottables

4.2.2.4. Assigning slottables and slots

4.2.2.5. Signaling slot change

4.2.3. Mutation algorithms

4.2.4. Mixin NonElementParentNode

4.2.5. Mixin DocumentOrShadowRoot

4.2.6. Mixin ParentNode

4.2.7. Mixin NonDocumentTypeChildNode

4.2.8. Mixin ChildNode

4.2.9. Mixin Slottable

4.2.10. Old-style collections: NodeList and HTMLCollection

4.2.10.1. Interface NodeList

4.2.10.2. Interface HTMLCollection

4.3. Mutation observers

4.3.1. Interface MutationObserver

4.3.2. Queuing a mutation record

4.3.3. Interface MutationRecord

4.4. Interface Node

4.5. Interface Document

4.5.1. Interface DOMImplementation

4.6. Interface DocumentType

4.7. Interface DocumentFragment

4.8. Interface ShadowRoot

4.9. Interface Element

4.9.1. Interface NamedNodeMap

4.9.2. Interface Attr

4.10. Interface CharacterData

4.11. Interface Text

4.12. Interface CDATASection

4.13. Interface ProcessingInstruction

4.14. Interface Comment

5. Ranges

5.1. Introduction to "DOM Ranges"

5.2. Boundary points

5.3. Interface AbstractRange

5.4. Interface StaticRange

5.5. Interface Range

6. Traversal

6.1. Interface NodeIterator

6.2. Interface TreeWalker

6.3. Interface NodeFilter

7. Sets

7.1. Interface DOMTokenList

8. XPath

8.1. Interface XPathResult

8.2. Interface XPathExpression

8.3. Mixin XPathEvaluatorBase

8.4. Interface XPathEvaluator

9. XSLT

2.2. Interface `Event`

2.3. Legacy extensions to the `Window` interface

2.4. Interface `CustomEvent`

2.7. Interface `EventTarget`

3.1. Interface `AbortController`

3.2. Interface `AbortSignal`

3.3. Using `AbortController` and `AbortSignal` objects in APIs

4.2.4. Mixin `NonElementParentNode`

4.2.5. Mixin `DocumentOrShadowRoot`

4.2.6. Mixin `ParentNode`

4.2.7. Mixin `NonDocumentTypeChildNode`

4.2.8. Mixin `ChildNode`

4.2.9. Mixin `Slottable`

4.2.10. Old-style collections: `NodeList` and `HTMLCollection`

4.2.10.1. Interface `NodeList`

4.2.10.2. Interface `HTMLCollection`

4.3.1. Interface `MutationObserver`

4.3.3. Interface `MutationRecord`

4.4. Interface `Node`

4.5. Interface `Document`

4.5.1. Interface `DOMImplementation`

4.6. Interface `DocumentType`

4.7. Interface `DocumentFragment`

4.8. Interface `ShadowRoot`

4.9. Interface `Element`

4.9.1. Interface `NamedNodeMap`

4.9.2. Interface `Attr`

4.10. Interface `CharacterData`

4.11. Interface `Text`

4.12. Interface `CDATASection`

4.13. Interface `ProcessingInstruction`

4.14. Interface `Comment`

5.3. Interface `AbstractRange`

5.4. Interface `StaticRange`

5.5. Interface `Range`

6.1. Interface `NodeIterator`

6.2. Interface `TreeWalker`

6.3. Interface `NodeFilter`

7.1. Interface `DOMTokenList`

8.1. Interface `XPathResult`

8.2. Interface `XPathExpression`

8.3. Mixin `XPathEvaluatorBase`

8.4. Interface `XPathEvaluator`

9.1. Interface `XSLTProcessor`