Group: WHATWG
H1: DOM
Shortname: dom
Text Macro: TWITTER thedomstandard
Text Macro: LATESTRD 2026-06
Abstract: DOM defines a platform-neutral model for events, aborting activities, and node trees.
Translation: ja https://triple-underscore.github.io/DOM4-ja.html
Translation: zh-Hans https://htmlspecs.com/dom/
Translation: ko https://ko.htmlspecs.com/dom/
Translate IDs: slottable slotable
Indent: 1

urlPrefix: https://www.w3.org/TR/xml/#NT-; spec: XML
 type: dfn
  text: Name; url: Name; for: XML
urlPrefix: https://www.w3.org/TR/xml-stylesheet/#; spec: XML-STYLESHEET
 type: dfn
  text: rules for parsing pseudo-attributes from a string; url: dt-parsing
  text: parsing result; url: dt-parsing-result
  text: pseudo-attribute; url: dt-pseudo-attribute
  text: name; url: dt-name; for: pseudo-attribute
  text: value; url: dt-value; for: pseudo-attribute
url: https://w3c.github.io/DOM-Parsing/#dom-range-createcontextualfragment
 type: method; text: createContextualFragment(); for: Range
type: interface
 url: https://w3c.github.io/touch-events/#idl-def-touchevent
  text: TouchEvent
 url: https://w3c.github.io/deviceorientation/spec-source-orientation.html#devicemotion
  text: DeviceMotionEvent
  text: DeviceOrientationEvent
urlPrefix: https://tc39.es/ecma262/#; spec: ECMASCRIPT
 text: Construct; url: sec-construct; type: abstract-op
 type: dfn
  text: current realm; url: current-realm
  text: realm; url: realm
  text: surrounding agent; url: surrounding-agent
urlPrefix: https://w3c.github.io/hr-time/#; spec: HR-TIME
 type:typedef; urlPrefix: dom-; text: DOMHighResTimeStamp
 type:dfn; text: current high resolution time; url: dfn-current-high-resolution-time
 type:dfn; text: relative high resolution coarse time; url: dfn-relative-high-resolution-coarse-time

spec:html; type:element
 text: head
 text: script
 text: title

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, Namespaces in XML, and Associating Style Sheets with XML documents. [[!ENCODING]] [[!SELECTORS4]] [[!TRUSTED-TYPES]] [[!WEBIDL]] [[!XML]] [[!XML-NAMES]] [[!XML-STYLESHEET]]

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.

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.

Ordered sets

Selectors

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

Name validation

This concept is used to validate [=/element=] [=Element/local names=], when constructed by DOM APIs. The intention is to allow any name that is possible to construct using the HTML parser (the branch where the first [=code point=] is an [=ASCII alpha=]), plus some additional possibilities. For those additional possibilities, the ASCII range is restricted for historical reasons, but beyond ASCII anything is allowed.

  /^(?:[A-Za-z][^\0\t\n\f\r\u0020/>]*|[:_\u0080-\u{10FFFF}][A-Za-z0-9-.:_\u0080-\u{10FFFF}]*)$/u
 

A [=string=] is a valid doctype name if it does not contain [=ASCII whitespace=], U+0000 NULL, or U+003E (>).

The empty string is a [=valid doctype name=].

Events

Introduction to "DOM Events"

obj.addEventListener("load", imgFetched)

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

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)

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 {{Event/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 {{Event/target}} attribute value will be the span element. The first time {{Event/currentTarget}} attribute's value will be the document, the second time the body element. {{Event/eventPhase}} attribute's value switches from {{Event/CAPTURING_PHASE}} to {{Event/BUBBLING_PHASE}}. If an event listener was registered for the span element, {{Event/eventPhase}} attribute's value would have been {{Event/AT_TARGET}}.

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 event path items. An event path item is a struct consisting 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 {{Event/type}} attribute value is set to type. The eventInitDict argument allows for setting the {{Event/bubbles}} and {{Event/cancelable}} attributes via object members of the same name.

event . {{Event/type}}

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

event . {{Event/target}}

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

event . {{Event/currentTarget}}

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

event . {{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 {{Event/currentTarget}}.

event . {{Event/eventPhase}}

Returns the event's phase, which is one of {{Event/NONE}}, {{Event/CAPTURING_PHASE}}, {{Event/AT_TARGET}}, and {{Event/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 . {{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 . {{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 {{Event/preventDefault()}} method.

event . preventDefault()

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

event . {{Event/defaultPrevented}}

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

event . {{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 . {{Event/isTrusted}}

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

event . {{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 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 {{Event/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 {{Event/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 {{Event/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 {{Event/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 {{Event/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.

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

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

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

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.

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;
};

event = new CustomEvent(type [, eventInitDict])

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

event . {{CustomEvent/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.

Constructing events

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.

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.

Defining event interfaces

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 {{Event/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 {{Event/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 {{EventListenerOptions/capture}}.

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

When set to true, options's {{AddEventListenerOptions/passive}} indicates that the callback will not cancel the event by invoking {{Event/preventDefault()}}. This is used to enable performance optimizations described in [[#observing-event-listeners]].

When set to true, options's {{AddEventListenerOptions/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 {{AddEventListenerOptions/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 {{Event/cancelable}} attribute value is false or its {{Event/preventDefault()}} method was not invoked; otherwise false.

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

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

In the future we could allow custom get the parent algorithms. If this would be useful, support issue #583. For now, all author-created {{EventTarget}}s do not participate in a tree structure.

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 {{Event/cancelable}} only when there is at least one non-{{AddEventListenerOptions/passive}} listener. For example, non-{{AddEventListenerOptions/passive}} {{TouchEvent}} listeners must block scrolling, but if all listeners are {{AddEventListenerOptions/passive}} then scrolling can be allowed to start in parallel by making the {{TouchEvent}} uncancelable (so that calls to {{Event/preventDefault()}} are ignored). So code dispatching an event is able to observe the absence of non-{{AddEventListenerOptions/passive}} listeners, and use that to clear the {{Event/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.)

Dispatching events

Firing events

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.

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 {{Event/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.

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 {{AbortController/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 {{AbortController/abort()}} by rejecting any unsettled promise with the {{AbortSignal}}'s [=AbortSignal/abort reason=].

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

startSpinner();

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

// …

controller.abort();

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

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

APIs that do not return promises can either react in an equivalent manner or opt to not surface the {{AbortSignal}}'s [=AbortSignal/abort reason=] at all. {{EventTarget/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.

Interface {{AbortController}}

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

  [SameObject] readonly attribute AbortSignal signal;

  undefined abort(optional any reason);
};

controller = new AbortController()

Returns a new controller whose {{AbortController/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 [=AbortSignal/abort reason=], and signal to any observers that the associated activity is to be aborted. If reason is undefined, then an "{{AbortError!!exception}}" {{DOMException}} will be stored.

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

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

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!!exception}}" {{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!!exception}}" {{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 [=AbortSignal/aborted=]), which is initially empty.

The [=AbortSignal/abort algorithms=] enable APIs with complex requirements to react in a reasonable way to {{AbortController/abort()}}. For example, a given API's [=AbortSignal/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 [=AbortSignal/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 [=AbortSignal/aborted=] state), which is initially empty.

The aborted getter steps are to return true if this is [=AbortSignal/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 [=AbortSignal/aborted=].

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

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

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

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

An {{AbortSignal}} object is aborted when its [=AbortSignal/abort reason=] is not undefined.

Garbage collection

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

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 [=AbortSignal/abort reason=].
• Reject immediately if the {{AbortSignal}} is already [=AbortSignal/aborted=], otherwise:
• Use the [=AbortSignal/abort algorithms=] mechanism to observe changes to the {{AbortSignal}} object and do so in a manner that does not lead to clashes with other observers.

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

Nodes

Introduction to "The DOM"

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>

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

Node tree

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

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

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

{{Document}}

In tree order:

1. Zero or more {{ProcessingInstruction}} or {{Comment}} nodes.

2. Optionally one {{DocumentType}} node.

3. Zero or more {{ProcessingInstruction}} or {{Comment}} nodes.

4. Optionally one {{Element}} node.

5. Zero or more {{ProcessingInstruction}} or {{Comment}} nodes.

{{DocumentFragment}}

{{Element}}

Zero or more {{Element}} or {{CharacterData}} nodes.

{{DocumentType}}

{{CharacterData}}

{{Attr}}

No children.

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

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

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

2. If node is a {{CharacterData}} node, then return node's data's length.

3. Return the number of node's children.

A node is considered empty if its length is 0.

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.

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.

Slots

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

A slot can only be created through HTML's <{slot}> element.

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

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

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

   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.

Slottables

{{Element}} and {{Text}} nodes are slottables.

A slot can be a slottable.

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

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

1. If localName is slot and namespace is null:

   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.

Finding slots and slottables

Assigning slottables and slots

Signaling slot change

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

Mutation algorithms

 const h1 = document.querySelector('h1');

 const fragment = new DocumentFragment();
 const script = fragment.appendChild(document.createElement('script'));
 const style = fragment.appendChild(document.createElement('style'));

 script.innerText= 'console.log(getComputedStyle(h1).color)'; // Logs 'rgb(255, 0, 0)'
 style.innerText = 'h1 {color: rgb(255, 0, 0);}';

 document.body.append(fragment);
 

Mixin {{NonElementParentNode}}

Web compatibility prevents the {{NonElementParentNode/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.

Mixin {{DocumentOrShadowRoot}}

interface mixin DocumentOrShadowRoot {
  readonly attribute CustomElementRegistry? customElementRegistry;
};
Document includes DocumentOrShadowRoot;
ShadowRoot includes DocumentOrShadowRoot;

registry = documentOrShadowRoot . {{DocumentOrShadowRoot/customElementRegistry}}

Returns documentOrShadowRoot's {{CustomElementRegistry}} object, if any; otherwise null.

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

Mixin {{ParentNode}}

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

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

  [CEReactions] undefined moveBefore(Node node, Node? child);

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

collection = node . {{ParentNode/children}}

Returns the child elements.

element = node . {{ParentNode/firstElementChild}}

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

element = node . {{ParentNode/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!!exception}}" {{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!!exception}}" {{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!!exception}}" {{DOMException}} if the constraints of the node tree are violated.

node . moveBefore(movedNode, child)

Moves, without first removing, movedNode into node after child if child is non-null; otherwise after the last child of node. This method preserves state associated with movedNode.

Throws a "{{HierarchyRequestError!!exception}}" {{DOMException}} if the constraints of the node tree are violated, or the state associated with the moved node cannot be preserved.

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.

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.

Mixin {{ChildNode}}

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

node . {{before(...nodes)}}

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

Throws a "{{HierarchyRequestError!!exception}}" {{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!!exception}}" {{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!!exception}}" {{DOMException}} if the constraints of the node tree are violated.

node . {{ChildNode/remove()}}

Removes node.

Mixin {{Slottable}}

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

Old-style collections: {{NodeList}} and {{HTMLCollection}}

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 . {{NodeList/length}}

Returns the number of nodes in the collection.

element = collection . {{NodeList/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.

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 . {{HTMLCollection/length}}

Returns the number of elements in the collection.

element = collection . {{HTMLCollection/item(index)}}

element = collection[index]

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

element = collection . {{namedItem(name)}}

element = collection[name]

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

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

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

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

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

1. Let result be an empty list.

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

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

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

3. Return result.

The namedItem(key) method steps are:

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

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

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

   or null if there is no such element.

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.

Each similar-origin window agent also has a mutation observer counter (a number), which is initially 0.

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 that is not a transient registered observer).

Transient registered observers are used to track mutations within a given node's descendants after node has been removed or moved so they do not get lost when {{MutationObserverInit/subtree}} is set to true on node's former parent. They are removed the next time mutation observers are notified.

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 creation index (a number) set on creation.
• A node list (a list of weak references to nodes), which is initially empty.
• A transient node set (a set 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 {{MutationObserver/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:

{{MutationObserverInit/childList}}

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

{{MutationObserverInit/attributes}}

Set to true if mutations to target's attributes are to be observed. Can be omitted if {{MutationObserverInit/attributeOldValue}} or {{MutationObserverInit/attributeFilter}} is specified.

{{MutationObserverInit/characterData}}

Set to true if mutations to target's data are to be observed. Can be omitted if {{MutationObserverInit/characterDataOldValue}} is specified.

{{MutationObserverInit/subtree}}

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

{{MutationObserverInit/attributeOldValue}}

Set to true if {{MutationObserverInit/attributes}} is true or omitted and target's attribute value before the mutation needs to be recorded.

{{MutationObserverInit/characterDataOldValue}}

Set to true if {{MutationObserverInit/characterData}} is set to true or omitted and target's data before the mutation needs to be recorded.

{{MutationObserverInit/attributeFilter}}

Set to a list of attribute local names (without namespace) if not all attribute mutations need to be observed and {{MutationObserverInit/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.

Queuing a mutation record

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 . {{MutationRecord/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 . {{MutationRecord/target}}

Returns the node the mutation affected, depending on the {{MutationRecord/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 . {{MutationRecord/addedNodes}}

record . {{MutationRecord/removedNodes}}

Return the nodes added and removed respectively.

record . {{MutationRecord/previousSibling}}

record . {{MutationRecord/nextSibling}}

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

record . {{MutationRecord/attributeName}}

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

record . {{MutationRecord/attributeNamespace}}

Returns the namespace of the changed attribute; otherwise null.

record . {{MutationRecord/oldValue}}

The return value depends on {{MutationRecord/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.

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 subtree = 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 . {{Node/nodeType}}

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

{{Element}}

{{Node}} . {{Node/ELEMENT_NODE}} (1).

{{Attr}}

{{Node}} . {{Node/ATTRIBUTE_NODE}} (2).

An exclusive Text node

{{Node}} . {{Node/TEXT_NODE}} (3).

{{CDATASection}}

{{Node}} . {{Node/CDATA_SECTION_NODE}} (4).

{{ProcessingInstruction}}

{{Node}} . {{Node/PROCESSING_INSTRUCTION_NODE}} (7).

{{Comment}}

{{Node}} . {{Node/COMMENT_NODE}} (8).

{{Document}}

{{Node}} . {{Node/DOCUMENT_NODE}} (9).

{{DocumentType}}

{{Node}} . {{Node/DOCUMENT_TYPE_NODE}} (10).

{{DocumentFragment}}

{{Node}} . {{Node/DOCUMENT_FRAGMENT_NODE}} (11).

node . {{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 . {{Node/baseURI}}

Returns node's node document's base URL.

The baseURI getter steps are:

1. Let baseURL be the result of running this's node document's get the base URL algorithm.

2. If baseURL is null, then set baseURL to this's node document's URL.

3. Return baseURL, serialized.

node . {{Node/isConnected}}

Returns true if node is connected; otherwise false.

node . {{Node/ownerDocument}}

Returns the node document. Returns null for documents.

node . {{Node/getRootNode()}}

Returns node's root.

node . getRootNode({ composed:true })

Returns node's shadow-including root.

node . {{Node/parentNode}}

Returns the parent.

node . {{Node/parentElement}}

Returns the parent element.

node . {{Node/hasChildNodes()}}

Returns whether node has children.

node . {{Node/childNodes}}

Returns the children.

node . {{Node/firstChild}}

Returns the first child.

node . {{Node/lastChild}}

Returns the last child.

node . {{Node/previousSibling}}

Returns the previous sibling.

node . {{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["{{GetRootNodeOptions/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 {{Node/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 of this with 0, this's length, and 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:

1. Let node be null.

2. If string is not the empty string, then set node to the result of creating a text node given parent's node document and string.

3. 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 of node with 0, node's length, and value.

Otherwise

Do nothing.

The {{Node/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 . {{Node/normalize()}}

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

node . cloneNode([subtree = false])

Returns a copy of node. If subtree is true, the copy also includes the node's descendants.

node . isEqualNode(otherNode)

Returns whether node and otherNode have the same properties.

node . {{compareDocumentPosition(other)}}

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

{{Node}} . {{Node/DOCUMENT_POSITION_DISCONNECTED}} (1)

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

{{Node}} . {{Node/DOCUMENT_POSITION_PRECEDING}} (2)

Set when other is preceding node.

{{Node}} . {{Node/DOCUMENT_POSITION_FOLLOWING}} (4)

Set when other is following node.

{{Node}} . {{Node/DOCUMENT_POSITION_CONTAINS}} (8)

Set when other is an ancestor of node.

{{Node}} . {{Node/DOCUMENT_POSITION_CONTAINED_BY}} (16, 10 in hexadecimal)

Set when other is a descendant of node.

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:

1. If this is other, then return zero.

2. Let node1 be other and node2 be this.

3. Let attr1 and attr2 be null.

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

5. If node2 is an attribute:

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

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

      1. For each attr of node2's attribute list:

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

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

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

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

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

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

9. If node1 is preceding node2, then return {{Node/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.

10. Return {{Node/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:

1. If element's namespace is namespace and its namespace prefix is non-null, then return its namespace prefix.

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

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

4. Return null.

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

{{Element}}

1. If prefix is "xml", then return the XML namespace.

2. If prefix is "xmlns", then return the XMLNS namespace.

3. If its namespace is non-null and its namespace prefix is prefix, then return namespace.

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

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

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

{{Document}}

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

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

{{DocumentType}}

{{DocumentFragment}}

Return null.

{{Attr}}

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

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

Otherwise

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

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

The lookupPrefix(namespace) method steps are:

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

2. Switch on the interface this implements:

   {{Element}}

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

   {{Document}}

   1. If this's document element is null, then return null.

   2. Return the result of locating a namespace prefix for this's document element using namespace.

   {{DocumentType}}

   {{DocumentFragment}}

   Return null.

   {{Attr}}

   1. If this's element is null, then return null.

   2. Return the result of locating a namespace prefix for this's element using namespace.

   Otherwise

   1. If this's parent element is null, then return null.

   2. Return the result of locating a namespace prefix for this's parent element using namespace.

The lookupNamespaceURI(prefix) method steps are:

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

2. Return the result of running locate a namespace for this using prefix.

The isDefaultNamespace(namespace) method steps are:

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

2. Let defaultNamespace be the result of running locate a namespace for this using null.

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

1. If qualifiedName is U+002A (*), then return an {{HTMLCollection}} rooted at root, whose filter matches only descendant elements.

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

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

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

2. If both namespace and localName are U+002A (*), then return an {{HTMLCollection}} rooted at root, whose filter matches descendant elements.

3. If namespace is U+002A (*), then return an {{HTMLCollection}} rooted at root, whose filter matches descendant elements whose local name is localName.

4. If localName is U+002A (*), then return an {{HTMLCollection}} rooted at root, whose filter matches descendant elements whose namespace is namespace.

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

1. Let classes be the result of running the ordered set parser on classNames.
2. If classes is the empty set, return an empty {{HTMLCollection}}.

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

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 or ImportNodeOptions) options = 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 {
  CustomElementRegistry? customElementRegistry;
  DOMString is;
};

dictionary ImportNodeOptions {
  CustomElementRegistry customElementRegistry;
  boolean selfOnly = false;
};

{{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"), allow declarative shadow roots (a boolean), and custom element registry (null or a {{CustomElementRegistry}} object). [[!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", allow declarative shadow roots is false, and custom element registry is null.

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.

Each document has an associated get the base URL algorithm, which returns a URL or null. Unless specified otherwise it returns null.

Each document has a base URL override (a URL or null), initially null.

The base URL override is set when cloning a document. HTML overrides the get the base URL algorithm to account for the base element and for the base URL "about:"-schemed documents inherit. [[!HTML]]

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

A document's get the parent algorithm, given an event, returns null if event's {{Event/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 . {{Document/implementation}}

Returns document's {{DOMImplementation}} object.

document . {{Document/URL}}

document . {{Document/documentURI}}

Returns document's URL.

document . {{Document/compatMode}}

Returns the string "BackCompat" if document's mode is "quirks"; otherwise "CSS1Compat".

document . {{Document/characterSet}}

Returns document's encoding.

document . {{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 {{DOMImplementation/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 . {{Document/doctype}}

Returns the doctype or null if there is none.

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

  <div id="example">
    <p id="p1" class="aaa bbb"/>
    <p id="p2" class="aaa ccc"/>
    <p id="p3" class="bbb ccc"/>
  </div>
 

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.

When supplied, options's {{ElementCreationOptions/customElementRegistry}} can be used to set the {{CustomElementRegistry}}.

When supplied, options's {{ElementCreationOptions/is}} can be used to create a customized built-in element.

If localName is not a valid element local name an "{{InvalidCharacterError}}" {{DOMException}} will be thrown.

When both options's {{ElementCreationOptions/customElementRegistry}} and options's {{ElementCreationOptions/is}} are supplied, a "{{NotSupportedError!!exception}}" {{DOMException}} will be thrown.

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.

When supplied, options's {{ElementCreationOptions/customElementRegistry}} can be used to set the {{CustomElementRegistry}}.

When supplied, options's {{ElementCreationOptions/is}} can be used to create a customized built-in element.

If qualifiedName is not a (possibly-prefixed) valid element local name an "{{InvalidCharacterError}}" {{DOMException}} will be thrown.

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

• Namespace prefix is non-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 both options's {{ElementCreationOptions/customElementRegistry}} and options's {{ElementCreationOptions/is}} are supplied, a "{{NotSupportedError!!exception}}" {{DOMException}} will be thrown.

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 [=XML/Name=] production an "{{InvalidCharacterError!!exception}}" {{DOMException}} will be thrown. If data contains "?>" an "{{InvalidCharacterError!!exception}}" {{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]]