HTML

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. 8.5.8 The XMLSerializer interface

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

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.

8.4.1 Opening the input stream

document = document.open()

✔MDN

Document/open

Support in all current engines.

Firefox1+Safari11+Chrome64+

---

Opera51+Edge79+

---

Edge (Legacy)12+Internet Explorer4+

---

Firefox Android?Safari iOS?Chrome Android?WebView Android?Samsung Internet?Opera Android47+

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 DOMException if the Document is an XML document.

Throws an 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:

1. If document is an XML document, then throw an DOMException exception.

2. If document's throw-on-dynamic-markup-insertion counter is greater than 0, then throw an "InvalidStateError" origin is not same origin to entryDocument's origin, then throw a DOMException.

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

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

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

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

7. For each shadow-including inclusive descendant node of document, erase all event listeners and handlers given node.

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

9. Replace all with null within document.

10. If document is fully active, then:

    1. Let newURL be a copy of entryDocument's URL.

    2. If entryDocument is not document, then set newURL's fragment to null.

    3. Run the URL and history update steps with document and newURL.

11. Set document's is initial about:blank to false.

12. If document's iframe load in progress flag is set, then set document's mute iframe load flag.

13. Set document to no-quirks mode.

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

15. Set the insertion point to point at just before the end of the input stream (which at this point will be empty).

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

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

1. If this is not fully active, then throw an DOMException exception.

2. Return the result of running the window open steps with url, name, and features.

8.4.2 Closing the input stream

document.close()

✔MDN

Document/close

Support in all current engines.

Firefox1+Safari11+Chrome64+

---

Opera51+Edge79+

---

Edge (Legacy)12+Internet Explorer4+

---

Firefox Android?Safari iOS?Chrome Android?WebView Android?Samsung Internet?Opera Android47+

Closes the input stream that was opened by the document.open() method.

Throws an DOMException if the Document is an XML document.

Throws an DOMException if the parser is currently executing a custom element constructor.

The close() method must run the following steps:

1. If XML document, then throw an this's throw-on-dynamic-markup-insertion counter is greater than zero, then throw an "InvalidStateError" this, then return.

2. Insert an explicit "EOF" character at the end of the parser's input stream.

3. If this's pending parsing-blocking script is not null, then return.

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

✔MDN

Document/write

Support in all current engines.

Firefox1+Safari1+Chrome1+

---

Opera3+Edge79+

---

Edge (Legacy)12+Internet Explorer4+

---

Firefox Android?Safari iOS?Chrome Android?WebView Android?Samsung Internet?Opera Android10.1+

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 DOMException when invoked on XML documents.

Throws an 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:

1. Let string be the empty string.

2. Let isTrusted be false if text contains a string; otherwise true.

3. For each value of text:

   1. If value is a TrustedHTML object, then append value's associated data to string.

   2. Otherwise, append value to string.

4. If isTrusted is false, set string to the result of invoking the Get Trusted Type compliant string algorithm with this's relevant global object, string, sink, and "script".

5. If lineFeed is true, append U+000A LINE FEED to string.

6. If document is an XML document, then throw an DOMException.

7. If document's throw-on-dynamic-markup-insertion counter is greater than 0, then throw an "InvalidStateError" DOMException.

8. If document's active parser was aborted is true, then return.

9. If the insertion point is undefined, then:

   1. If document's unload counter is greater than 0 or document's ignore-destructive-writes counter is greater than 0, then return.

   2. Run the document open steps with document.

10. Insert string into the input stream just before the insertion point.

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

8.4.4 document.writeln()

document.writeln(...text)

✔MDN

Document/writeln

Support in all current engines.

Firefox1+Safari11+Chrome64+

---

Opera51+Edge79+

---

Edge (Legacy)12+Internet Explorer4+

---

Firefox Android?Safari iOS?Chrome Android?WebView Android?Samsung Internet?Opera Android47+

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 DOMException when invoked on XML documents.

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

8.5 DOM parsing and serialization APIs

partial interface Element {
  [CEReactions] undefined setHTMLUnsafe((TrustedHTML or DOMString) html);
  DOMString getHTML(optional GetHTMLOptions options = {});

  [CEReactions] attribute (LegacyNullToEmptyString] DOMString) innerHTML;
  [CEReactions] attribute (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 (LegacyNullToEmptyString] DOMString) innerHTML;
};

dictionary GetHTMLOptions {
  boolean serializableShadowRoots = false;
  sequence<ShadowRoot> shadowRoots = [];
};

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

partial interface Range {
  [CEReactions, NewObject] TrustedHTML or DOMString) string);
};

[Exposed=Window]
interface XMLSerializer {
  constructor();

  DOMString serializeToString(Node root);
};