JavaScript Document parseHTML() Method

What You’ll Learn

Document.parseHTML() is a static method that parses and sanitizes an HTML string into a new Document that is XSS-safe (MDN). Learn default vs custom Sanitizer options, how it differs from parseHTMLUnsafe() and DOMParser, feature detection, and five examples with try-it labs.

Introduction

Sometimes you need a whole Document from an HTML string—not just inject into one element. Older code often used DOMParser.parseFromString(html, "text/html"), which parses without the built-in XSS sanitizer that parseHTML() provides.

MDN: Document.parseHTML(input, options) parses and sanitizes the string and returns a new Document. The result has content type "text/html", character set UTF-8, and URL "about:blank".

Related tutorials: Element.setHTML(), Document constructor, contentType.

Understanding Document.parseHTML()

A static method on the Document interface—call it as Document.parseHTML(...), not on document instances (though engines may also expose it there).

• input — HTML string to sanitize and parse (MDN).
• options.sanitizer — optional Sanitizer, SanitizerConfig, or "default" (MDN).
• Returns — a new Document (MDN).
• Always sanitizes — removes XSS-unsafe elements/attributes (like after Sanitizer.removeUnsafe()) (MDN).
• Declarative shadow roots — supported; only the first shadow root per host is created (MDN).
• TypeError — invalid sanitizer config or value (MDN).

📝 Syntax

Document.parseHTML(input)
Document.parseHTML(input, options)

Parameters

• input — string of HTML to sanitize and parse into a Document (MDN).
• options (optional) — object with sanitizer: a Sanitizer, SanitizerConfig, or the string "default". If omitted, the default sanitizer is used (MDN).

Return value

A Document (MDN).

Exceptions

• TypeError — invalid SanitizerConfig (e.g. both allowed and removed settings), a string other than "default", or a value that is not a Sanitizer / SanitizerConfig / string (MDN).

Common patterns

const html = '<p>Hello</p><script>alert(1)</script>';

// Default sanitizer (MDN)
const doc = Document.parseHTML(html);

// Custom Sanitizer (reuse for efficiency, MDN)
const sanitizer = new Sanitizer({ elements: ["div", "p", "span"] });
const doc2 = Document.parseHTML(html, { sanitizer });

// Explicit default
const doc3 = Document.parseHTML(html, { sanitizer: "default" });

⚖️ parseHTML vs parseHTMLUnsafe vs DOMParser

Examples Gallery

Examples follow MDN Document: parseHTML(). Feature-detect Document.parseHTML in try-it labs—support is still limited.

const html = '<p>Hello</p><script>alert(1)</script>';
const doc = Document.parseHTML(html);

console.log(doc.body.innerHTML);
// "<p>Hello</p>" — script removed

<p>Hello</p>

const doc = Document.parseHTML("<h1>Title</h1>");

console.log({
  contentType: doc.contentType,   // "text/html"
  characterSet: doc.characterSet, // "UTF-8"
  URL: doc.URL                    // "about:blank"
});

{ contentType: "text/html", characterSet: "UTF-8", URL: "about:blank" }

const html = '<div><p>Hi</p><script>alert(1)</script></div>';
const sanitizer = new Sanitizer({
  elements: ["div", "p", "script"] // script still removed (MDN)
});

const doc = Document.parseHTML(html, { sanitizer });
console.log(doc.body.innerHTML);

<div><p>Hi</p></div>

function parseSafeHtml(html) {
  if (typeof Document.parseHTML === "function") {
    return Document.parseHTML(html);
  }
  // Fallback: wider support, but no built-in XSS strip — sanitize yourself
  return new DOMParser().parseFromString(html, "text/html");
}

const doc = parseSafeHtml("<p>OK</p>");
console.log(doc.body.textContent);

OK

const userHtml = '<article><p>Comment</p><script>evil()</script></article>';
const parsed = Document.parseHTML(userHtml);
const host = document.getElementById("host");

// Import children into the current document
[...parsed.body.childNodes].forEach(function (node) {
  host.append(document.importNode(node, true));
});

console.log(host.innerHTML);

<article><p>Comment</p></article>

🚀 Common Use Cases

• Untrusted HTML strings — build a Document without running scripts (MDN).
• Offline / preview documents — inspect body, title, or links before display.
• CMS / markdown output — parse sanitized HTML batches into Documents.
• Safer alternative to DOMParser — when Sanitizer API support is available.
• Custom allow-lists — reuse a Sanitizer instance (MDN efficiency tip).
• Not for element injection alone — use setHTML() when targeting one node.

📝 Notes

• MDN: Limited availability (not Baseline)—feature-detect before production use.
• Not Deprecated, Experimental, or Non-standard — defined in the HTML specification.
• Always removes XSS-unsafe elements/attributes, even with permissive sanitizers (MDN).
• Prefer over parseHTMLUnsafe() unless you need unsafe HTML (MDN).
• Trusted Types are not used to gate this method because it always sanitizes (MDN).
• Related: setHTML(), contentType, characterSet, JavaScript hub.

💡 Best Practices