HTML
Living Standard — Last Updated 22 November 2024
Living Standard — Last Updated 22 November 2024
APIs for dynamically inserting markup into the document interact with the parser, and thus their behavior varies depending on whether they are used with HTML documents (and the HTML parser) or XML documents (and the XML parser).
Document objects have a throw-on-dynamic-markup-insertion counter,
which is used in conjunction with the create an element for the token algorithm to
prevent custom element constructors from being
able to use document.open(), document.close(), and document.write() when they are invoked by the parser.
Initially, the counter must be set to zero.
document = document.open()Support in all current engines.
Causes the Document to be replaced in-place, as if it was a new
Document object, but reusing the previous object, which is then returned.
The resulting Document has an HTML parser associated with it, which can be given
data to parse using document.write().
The method has no effect if the Document is still being parsed.
Throws an "InvalidStateError" DOMException if the
Document is an XML document.
Throws an "InvalidStateError" DOMException if the
parser is currently executing a custom element constructor.
window = document.open(url, name, features)Works like the window.open() method.
Document objects have an active parser was aborted boolean, which is
used to prevent scripts from invoking the document.open()
and document.write() methods (directly or indirectly)
after the document's active parser has been aborted. It is initially false.
The document open steps, given a document, are as follows:
If document is an XML document, then throw
an "InvalidStateError" DOMException exception.
If document's throw-on-dynamic-markup-insertion counter is greater
than 0, then throw an "InvalidStateError"
DOMException.
Let entryDocument be the entry global object's associated Document.
If document's origin is not
same origin to entryDocument's origin, then throw a
"SecurityError" DOMException.
If document has an active parser whose script nesting level is greater than 0, then return document.
This basically causes document.open() to
be ignored when it's called in an inline script found during parsing, while still letting it
have an effect when called from a non-parser task such as a timer callback or event handler.
Similarly, if document's unload counter is greater than 0, then return document.
This basically causes document.open() to
be ignored when it's called from a beforeunload, pagehide, or unload event
handler while the Document is being unloaded.
If document's active parser was aborted is true, then return document.
This notably causes document.open() to
be ignored if it is called after a navigation has started, but
only during the initial parse. See issue
#4723 for more background.
If document's node navigable is non-null and document's node navigable's ongoing navigation is a navigation ID, then stop loading document's node navigable.
For each shadow-including inclusive descendant node of document, erase all event listeners and handlers given node.
If document is the associated
Document of document's relevant global object, then
erase all event listeners and handlers given document's relevant
global object.
Replace all with null within document.
If document is fully active, then:
Let newURL be a copy of entryDocument's URL.
If entryDocument is not document, then set newURL's fragment to null.
Run the URL and history update steps with document and newURL.
Set document's is initial about:blank to
false.
If document's iframe load in progress flag is set, then set document's mute iframe load flag.
Set document to no-quirks mode.
Create a new HTML parser and associate it with document. This is a
script-created parser (meaning that it can be closed by the document.open() and document.close() methods, and that the tokenizer will wait for
an explicit call to document.close() before emitting an
end-of-file token). The encoding confidence is
irrelevant.
Set the insertion point to point at just before the end of the input stream (which at this point will be empty).
Update the current document readiness of document to "loading".
This causes a readystatechange
event to fire, but the event is actually unobservable to author code, because of the previous
step which erased all event listeners and
handlers that could observe it.
Return document.
The document open steps do not affect whether a Document
is ready for post-load tasks or completely loaded.
The open(unused1,
unused2) method must return the result of running the document open
steps with this.
The unused1 and
unused2 arguments are ignored, but kept in the IDL to allow code that calls the
function with one or two arguments to continue working. They are necessary due to Web IDL
overload resolution algorithm rules, which would throw a TypeError
exception for such calls had the arguments not been there. whatwg/webidl issue #581 investigates
changing the algorithm to allow for their removal. [WEBIDL]
The open(url,
name, features) method must run these steps:
If this is not fully active, then throw an
"InvalidAccessError" DOMException exception.
Return the result of running the window open steps with url, name, and features.
document.close()Support in all current engines.
Closes the input stream that was opened by the document.open() method.
Throws an "InvalidStateError" DOMException if the
Document is an XML document.
Throws an "InvalidStateError" DOMException if the
parser is currently executing a custom element constructor.
The close() method must run the following
steps:
If this is an XML document, then throw
an "InvalidStateError" DOMException.
If this's throw-on-dynamic-markup-insertion counter is greater
than zero, then throw an "InvalidStateError"
DOMException.
If there is no script-created parser associated with this, then return.
Insert an explicit "EOF" character at the end of the parser's input stream.
If this's pending parsing-blocking script is not null, then return.
Run the tokenizer, processing resulting tokens as they are emitted, and stopping when the tokenizer reaches the explicit "EOF" character or spins the event loop.
document.write()document.write(...text)Support in all current engines.
In general, adds the given string(s) to the Document's input stream.
This method has very idiosyncratic behavior. In some cases, this method can
affect the state of the HTML parser while the parser is running, resulting in a DOM
that does not correspond to the source of the document (e.g. if the string written is the string
"<plaintext>" or "<!--"). In other cases,
the call can clear the current page first, as if document.open() had been called. In yet more cases, the method
is simply ignored, or throws an exception. Users agents are explicitly allowed to avoid executing
script elements inserted via this method. And to make matters even worse, the
exact behavior of this method can in some cases be dependent on network latency, which can lead to failures that are very hard to debug. For all these reasons, use
of this method is strongly discouraged.
Throws an "InvalidStateError" DOMException when
invoked on XML documents.
Throws an "InvalidStateError" DOMException if the
parser is currently executing a custom element constructor.
This method performs no sanitization to remove potentially-dangerous elements
and attributes like script or event handler content attributes.
Document objects have an ignore-destructive-writes counter, which is
used in conjunction with the processing of script elements to prevent external
scripts from being able to use document.write() to blow
away the document by implicitly calling document.open().
Initially, the counter must be set to zero.
The document write steps, given a Document object document,
a list text, a boolean lineFeed and a string sink, are as
follows:
Let string be the empty string.
Let isTrusted be false if text contains a string; otherwise true.
For each value of text:
If value is a TrustedHTML object, then
append value's associated data to
string.
Otherwise, append value to string.
If isTrusted is false, set string to the result of invoking the
Get Trusted Type compliant string algorithm with
TrustedHTML, this's relevant global
object, string, sink, and "script".
If lineFeed is true, append U+000A LINE FEED to string.
If document is an XML document, then throw
an "InvalidStateError" DOMException.
If document's throw-on-dynamic-markup-insertion counter is greater
than 0, then throw an "InvalidStateError"
DOMException.
If document's active parser was aborted is true, then return.
If the insertion point is undefined, then:
If document's unload counter is greater than 0 or document's ignore-destructive-writes counter is greater than 0, then return.
Run the document open steps with document.
Insert string into the input stream just before the insertion point.
If document's pending parsing-blocking script is null, then have the
HTML parser process string, one code point at a time, processing
resulting tokens as they are emitted, and stopping when the tokenizer reaches the insertion
point or when the processing of the tokenizer is aborted by the tree construction stage (this
can happen if a script end tag token is emitted by the tokenizer).
If the document.write() method was
called from script executing inline (i.e. executing because the parser parsed a set of
script tags), then this is a reentrant invocation of the
parser. If the parser pause flag is set, the tokenizer will abort immediately
and no HTML will be parsed, per the tokenizer's parser pause
flag check.
The document.write(...text) method steps are
to run the document write steps with this, text, false, and
"Document write".
document.writeln()document.writeln(...text)Support in all current engines.
Adds the given string(s) to the Document's input stream, followed by a newline
character. If necessary, calls the open() method
implicitly first.
Throws an "InvalidStateError" DOMException when
invoked on XML documents.
Throws an "InvalidStateError" DOMException if the
parser is currently executing a custom element constructor.
This method performs no sanitization to remove potentially-dangerous elements
and attributes like script or event handler content attributes.
The document.writeln(...text) method steps are
to run the document write steps with this, text, true, and
"Document writeln".
Support in all current engines.
partial interface Element {
[CEReactions ] undefined setHTMLUnsafe ((TrustedHTML or DOMString ) html );
DOMString getHTML (optional GetHTMLOptions options = {});
[CEReactions ] attribute (TrustedHTML or [LegacyNullToEmptyString ] DOMString ) innerHTML ;
[CEReactions ] attribute (TrustedHTML or [LegacyNullToEmptyString ] DOMString ) outerHTML ;
[CEReactions ] undefined insertAdjacentHTML (DOMString position , (TrustedHTML or DOMString ) string );
};
partial interface ShadowRoot {
[CEReactions ] undefined setHTMLUnsafe ((TrustedHTML or DOMString ) html );
DOMString getHTML (optional GetHTMLOptions options = {});
[CEReactions ] attribute (TrustedHTML or [LegacyNullToEmptyString ] DOMString ) innerHTML ;
};
dictionary GetHTMLOptions {
boolean serializableShadowRoots = false ;
sequence <ShadowRoot > shadowRoots = [];
};DOMParser interfaceThe DOMParser interface allows authors to create new Document objects
by parsing strings, as either HTML or XML.
parser = new DOMParser()Support in all current engines.
Constructs a new DOMParser object.
document = parser.parseFromString(string, type)Support in all current engines.
Parses string using either the HTML or XML parser, according to type,
and returns the resulting Document. type can be "text/html"
(which will invoke the HTML parser), or any of "text/xml",
"application/xml", "application/xhtml+xml", or
"image/svg+xml" (which will invoke the XML parser).
For the XML parser, if string cannot be parsed, then the returned
Document will contain elements describing the resulting error.
Note that script elements are not evaluated during parsing, and the resulting
document's encoding will always be
UTF-8. The document's URL will be
inherited from parser's relevant global object.
Values other than the above for type will cause a TypeError exception
to be thrown.
The design of DOMParser, as a class that needs to be constructed and
then have its parseFromString() method
called, is an unfortunate historical artifact. If we were designing this functionality today it
would be a standalone function. For parsing HTML, the modern alternative is Document.parseHTMLUnsafe().
This method performs no sanitization to remove potentially-dangerous elements
and attributes like script or event handler content attributes.
[Exposed =Window ]
interface DOMParser {
constructor ();
[NewObject ] Document parseFromString ((TrustedHTML or DOMString ) string , DOMParserSupportedType type );
};
enum DOMParserSupportedType {
" text/html " ,
" text/xml " ,
" application/xml " ,
" application/xhtml+xml " ,
" image/svg+xml "
};The new DOMParser() constructor
steps are to do nothing.
The parseFromString(string,
type) method steps are:
Let compliantString be the result of invoking the Get Trusted Type compliant string algorithm with TrustedHTML, this's relevant global
object, string, "DOMParser parseFromString", and "script".
Let document be a new Document, whose content type is type and URL is this's relevant global object's associated Document's URL.
The document's encoding will
be left as its default, of UTF-8. In particular, any XML declarations or
meta elements found while parsing compliantString will have no effect.
Switch on type:
text/html"Parse HTML from a string given document and compliantString.
Since document does not have a browsing context, scripting is disabled.
Create an XML parser parser, associated with document, and with XML scripting support disabled.
Parse compliantString using parser.
If the previous step resulted in an XML well-formedness or XML namespace well-formedness error, then:
Assert: document has no child nodes.
Let root be the result of creating an
element given document, "parsererror", and "http://www.mozilla.org/newlayout/xml/parsererror.xml".
Optionally, add attributes or children to root to describe the nature of the parsing error.
Append root to document.
Return document.
To parse HTML from a string, given a Document document and a
string html:
Set document's type to "html".
Create an HTML parser parser, associated with document.
Place html into the input stream for parser. The encoding confidence is irrelevant.
Start parser and let it run until it has consumed all the characters just inserted into the input stream.
This might mutate the document's mode.
element.setHTMLUnsafe(html)Parses html using the HTML parser, and replaces the children of element with the result. element provides context for the HTML parser.
shadowRoot.setHTMLUnsafe(html)Parses html using the HTML parser, and replaces the children of shadowRoot with the result. shadowRoot's host provides context for the HTML parser.
doc = Document.parseHTMLUnsafe(html)Parses html using the HTML parser, and returns the resulting
Document.
Note that script elements are not evaluated during parsing, and the resulting
document's encoding will always be
UTF-8. The document's URL will be
about:blank.
These methods perform no sanitization to remove potentially-dangerous elements
and attributes like script or event handler content attributes.
Element's setHTMLUnsafe(html) method steps
are:
Let compliantHTML be the result of invoking the Get Trusted Type compliant string algorithm with TrustedHTML, this's relevant global
object, html, "Element setHTMLUnsafe", and "script".
Let target be this's template contents if
this is a template element; otherwise this.
Unsafely set HTML given target, this, and compliantHTML.
ShadowRoot's setHTMLUnsafe(html) method steps
are:
Let compliantHTML be the result of invoking the Get Trusted Type compliant string algorithm with TrustedHTML, this's relevant global
object, html, "ShadowRoot setHTMLUnsafe", and "script".
Unsafely set HTML given this, this's shadow host, and compliantHTML.
To unsafely set HTML, given an Element or DocumentFragment
target, an Element contextElement, and a string
html:
Let newChildren be the result of the HTML fragment parsing algorithm given contextElement, html, and true.
Let fragment be a new DocumentFragment whose node
document is contextElement's node document.
For each node in newChildren, append node to fragment.
Replace all with fragment within target.
The static parseHTMLUnsafe(html) method steps are:
Let compliantHTML be the result of invoking the Get Trusted Type compliant string algorithm with TrustedHTML, this's relevant global
object, html, "Document parseHTMLUnsafe", and "script".
Let document be a new Document, whose content type is "text/html".
Since document does not have a browsing context, scripting is disabled.
Set document's allow declarative shadow roots to true.
Parse HTML from a string given document and compliantHTML.
Return document.
html = element.getHTML({ serializableShadowRoots, shadowRoots })Returns the result of serializing element to HTML. Shadow roots within element are serialized according to the provided options:
If serializableShadowRoots is true, then all shadow roots marked as serializable are serialized.
If the shadowRoots array is provided, then all shadow roots specified in the array are serialized, regardless of whether or not they are marked as serializable.
If neither option is provided, then no shadow roots are serialized.
html = shadowRoot.getHTML({ serializableShadowRoots, shadowRoots })Returns the result of serializing shadowRoot to HTML, using its shadow host as the context element. Shadow roots within shadowRoot are serialized according to the provided options, as above.
Element's getHTML(options) method steps
are to return the result of HTML fragment serialization algorithm with
this, options["serializableShadowRoots"],
and options["shadowRoots"].
ShadowRoot's getHTML(options) method steps
are to return the result of HTML fragment serialization algorithm with
this, options["serializableShadowRoots"],
and options["shadowRoots"].
innerHTML propertyThe innerHTML property has a number of outstanding issues
in the DOM Parsing and Serialization issue
tracker, documenting various problems with its specification.
element.innerHTMLReturns a fragment of HTML or XML that represents the element's contents.
In the case of an XML document, throws a "InvalidStateError"
DOMException if the element cannot be serialized to XML.
element.innerHTML = valueReplaces the contents of the element with nodes parsed from the given string.
In the case of an XML document, throws a "SyntaxError"
DOMException if the given string is not well-formed.
shadowRoot.innerHTMLReturns a fragment of HTML that represents the shadow roots's contents.
shadowRoot.innerHTML = valueReplaces the contents of the shadow root with nodes parsed from the given string.
These properties' setters perform no sanitization to remove
potentially-dangerous elements and attributes like script or event handler
content attributes.
The fragment serializing algorithm steps, given an Element,
Document or DocumentFragment node and a boolean require
well-formed, are:
Let context document be node's node document.
If context document is an HTML document, return the result of HTML fragment serialization algorithm with node, false, and « ».
Return the XML serialization of node given require well-formed.
The fragment parsing algorithm steps, given an Element
context and a string markup, are:
Let algorithm be the HTML fragment parsing algorithm.
If context's node document is an XML document, then set algorithm to the XML fragment parsing algorithm.
Let new children be the result of invoking algorithm given markup, with context set to context.
Let fragment be a new DocumentFragment whose node
document is context's node document.
Append each Node in new
children to fragment (in tree order).
This ensures the node document for the new nodes is correct.
Return fragment.
Element's innerHTML getter steps are to return the result of
running fragment serializing algorithm steps with this and true.
ShadowRoot's innerHTML getter steps are to return the result of
running fragment serializing algorithm steps with this and true.
Element's innerHTML setter steps
are:
Let compliantString be the result of invoking the Get Trusted Type compliant string algorithm with TrustedHTML, this's relevant global
object, the given value, "Element innerHTML", and "script".
Let context be this.
Let fragment be the result of invoking the fragment parsing algorithm steps with context and compliantString.
If context is a template element, then set context to
the template element's template contents (a
DocumentFragment).
Setting innerHTML on a
template element will replace all the nodes in its template contents
rather than its children.
Replace all with fragment within context.
ShadowRoot's innerHTML setter
steps are:
Let compliantString be the result of invoking the Get Trusted Type compliant string algorithm with TrustedHTML, this's relevant global
object, the given value, "ShadowRoot innerHTML", and "script".
Let fragment be the result of invoking the fragment parsing algorithm steps with context and compliantString.
Replace all with fragment within this.
outerHTML propertyThe outerHTML property has a number of outstanding issues
in the DOM Parsing and Serialization issue
tracker, documenting various problems with its specification.
element.outerHTMLReturns a fragment of HTML or XML that represents the element and its contents.
In the case of an XML document, throws a "InvalidStateError"
DOMException if the element cannot be serialized to XML.
element.outerHTML = valueReplaces the element with nodes parsed from the given string.
In the case of an XML document, throws a "SyntaxError"
DOMException if the given string is not well-formed.
Throws a "NoModificationAllowedError" DOMException if
the parent of the element is a Document.
This property's setter performs no sanitization to remove potentially-dangerous
elements and attributes like script or event handler content
attributes.
Element's outerHTML getter steps are:
Let element be a fictional node whose only child is this.
Return the result of running fragment serializing algorithm steps with element and true.
Element's outerHTML setter steps
are:
Let compliantString be the result of invoking the Get Trusted Type compliant string algorithm with TrustedHTML, this's relevant global
object, the given value, "Element outerHTML", and "script".
If parent is null, return. There would be no way to obtain a reference to the nodes created even if the remaining steps were run.
If parent is a Document, throw a
"NoModificationAllowedError" DOMException.
If parent is a DocumentFragment, set parent to the
result of creating an element given this's
node document, body, and the HTML namespace.
Let fragment be the result of invoking the fragment parsing algorithm steps given parent and compliantString.
insertAdjacentHTML() methodThe insertAdjacentHTML()
method has a number of outstanding issues in the DOM Parsing and Serialization issue tracker, documenting various problems
with its specification.
element.insertAdjacentHTML(position, string)Parses string as HTML or XML and inserts the resulting nodes into the tree in the position given by the position argument, as follows:
beforebegin"afterbegin"beforeend"afterend"Throws a "SyntaxError" DOMException if the arguments
have invalid values (e.g., in the case of an XML document,
if the given string is not well-formed).
Throws a "NoModificationAllowedError" DOMException
if the given position isn't possible (e.g. inserting elements after the root element of a
Document).
This method performs no sanitization to remove potentially-dangerous elements
and attributes like script or event handler content attributes.
Element's insertAdjacentHTML(position,
string) method steps are:
Let compliantString be the result of invoking the Get Trusted Type compliant string algorithm with TrustedHTML, this's relevant global
object, string, "Element insertAdjacentHTML", and "script".
Let context be null.
Use the first matching item from this list:
beforebegin"afterend"If context is null or a Document, throw a
"NoModificationAllowedError" DOMException.
afterbegin"beforeend"Throw a "SyntaxError" DOMException.
If context is not an Element or all of the following are true:
context's node document is an HTML document;
context's local name is
"html"; and
context's namespace is the HTML namespace,
set context to the result of creating an
element given this's node document, body, and
the HTML namespace.
Let fragment be the result of invoking the fragment parsing algorithm steps with context and compliantString.
beforebegin"afterbegin"Insert fragment into this before its first child.
beforeend"afterend"Insert fragment into this's parent before this's next sibling.
As with other direct Node-manipulation APIs (and unlike innerHTML), insertAdjacentHTML() does not include any special
handling for template elements. In most cases you will want to use templateEl.content.insertAdjacentHTML() instead of directly
manipulating the child nodes of a template element.
createContextualFragment()
methodThe createContextualFragment() method has a number
of outstanding issues in the DOM Parsing and Serialization issue tracker, documenting various problems
with its specification.
docFragment = range.createContextualFragment(string)Returns a DocumentFragment created from the markup string string using
range's start node as the context in
which fragment is parsed.
This method performs no sanitization to remove potentially-dangerous elements
and attributes like script or event handler content attributes.
partial interface Range {
[CEReactions , NewObject ] DocumentFragment createContextualFragment ((TrustedHTML or DOMString ) string );
};Range's createContextualFragment(string)
method steps are:
Let compliantString be the result of invoking the Get
Trusted Type compliant string algorithm with TrustedHTML, this's relevant global
object, string, "Range createContextualFragment", and
"script".
Let node be this's start node.
Let element be null.
If node implements Element, set element
to node.
Otherwise, if node implements Text or
Comment, set element to node's parent
element.
If element is null or all of the following are true:
element's node document is an HTML document;
element's local name is
"html"; and
element's namespace is the HTML namespace,
then set element to the result of creating an
element given this's node document, body, and the
HTML namespace.
Let fragment node be the result of invoking the fragment parsing algorithm steps with element and compliantString.
For each script of fragment node's
script element descendants:
Set script's already started to false.
Set script's parser document to null.
Return fragment node.