HTML: The Living Standard

Edition for Web Developers — Last Updated 21 November 2024

1. 1. 8.4 Dynamic markup insertion
      1. 8.4.1 Opening the input stream
      2. 8.4.2 Closing the input stream
      3. 8.4.3 document.write()
      4. 8.4.4 document.writeln()
   2. 8.5 DOM parsing and serialization APIs
      1. 8.5.1 The DOMParser interface
      2. 8.5.2 Unsafe HTML parsing methods
      3. 8.5.3 HTML serialization methods
      4. 8.5.4 The innerHTML property
      5. 8.5.5 The outerHTML property
      6. 8.5.6 The insertAdjacentHTML() method
      7. 8.5.7 The createContextualFragment() method

8.4 Dynamic markup insertion

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

8.4.1 Opening the input stream

document = document.open()

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.

8.4.2 Closing the input stream

document.close()

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.

8.4.3 document.write()

document.write(...text)

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.

8.4.4 document.writeln()

document.writeln(...text)

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.

8.5 DOM parsing and serialization APIs

8.5.1 The DOMParser interface

The DOMParser interface allows authors to create new Document objects by parsing strings, as either HTML or XML.

parser = new DOMParser()

Constructs a new DOMParser object.

document = parser.parseFromString(string, type)

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.

8.5.2 Unsafe HTML parsing methods

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.

8.5.3 HTML serialization methods

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.

8.5.4 The innerHTML property

The innerHTML property has a number of outstanding issues in the DOM Parsing and Serialization issue tracker, documenting various problems with its specification.

element.innerHTML

Returns 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 = value

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

Returns a fragment of HTML that represents the shadow roots's contents.

shadowRoot.innerHTML = value

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

8.5.5 The outerHTML property

The outerHTML property has a number of outstanding issues in the DOM Parsing and Serialization issue tracker, documenting various problems with its specification.

element.outerHTML

Returns 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 = value

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

8.5.6 The insertAdjacentHTML() method

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

Before the element itself (i.e., after element's previous sibling)

"afterbegin"

Just inside the element, before its first child.

"beforeend"

Just inside the element, after its last child.

"afterend"

After the element itself (i.e., before element's next sibling)

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.

8.5.7 The createContextualFragment() method

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