HTML: The Living Standard

Edition for Web Developers — Last Updated 16 January 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
      1. 8.5.1 The DOMParser interface
      2. 8.5.2 Unsafe HTML parsing methods

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.

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.

8.5 DOM parsing

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

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.