JavaScript Document parseHTMLUnsafe() Method

What You’ll Learn

Document.parseHTMLUnsafe() is a static method that parses HTML into a new Document with optional sanitization. Learn MDN’s injection-sink warnings, when to prefer parseHTML(), TrustedHTML + Trusted Types, default and custom Sanitizer options, declarative shadow roots, and five try-it labs.

Introduction

Sometimes you need a full Document from an HTML string—not just inject into one element. Document.parseHTMLUnsafe(input, options) creates that Document, optionally filters unwanted tags, and supports declarative shadow roots in the input (MDN).

The “Unsafe” suffix is deliberate: without a sanitizer, every HTML entity in the string is injected. MDN warns this is an injection sink and a possible XSS vector when the input comes from attackers. On browsers where it exists, MDN says parseHTML() should almost always be used instead.

Related tutorials: parseHTML(), setHTML(), setHTMLUnsafe(), Document constructor.

Understanding Document.parseHTMLUnsafe()

A static method on Document—call Document.parseHTMLUnsafe(...), not on live document instances.

• input — TrustedHTML instance or HTML string (MDN).
• options.sanitizer — optional Sanitizer, SanitizerConfig, or "default". If omitted, no sanitizer runs (MDN).
• Returns — a new Document with text/html, UTF-8, about:blank (MDN).
• Declarative shadow roots — parsed; only the first per host is created (MDN).
• Does not enforce XSS removal — unlike parseHTML() (MDN).
• TypeError — invalid sanitizer config or value (MDN).

📝 Syntax

Document.parseHTMLUnsafe(input)
Document.parseHTMLUnsafe(input, options)

Parameters

• input — TrustedHTML or HTML string to parse (MDN).
• options.sanitizer (optional) — Sanitizer, SanitizerConfig, or "default" (XSS-safe default config). If omitted, no sanitizer is used (MDN).

Return value

A Document (MDN).

Exceptions

• TypeError — invalid SanitizerConfig, string other than "default", or non-Sanitizer value (MDN).

Common patterns

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

// No sanitizer — injection sink (trusted HTML only!)
const doc = Document.parseHTMLUnsafe(html);

// Default XSS-safe sanitizer (MDN)
const safeDoc = Document.parseHTMLUnsafe(html, { sanitizer: "default" });

// TrustedHTML — policy already sanitized
const trusted = policy.createHTML(html);
const trustedDoc = Document.parseHTMLUnsafe(trusted);

// Custom sanitizer — can allow script unlike parseHTML() (MDN)
const sanitizer = new Sanitizer({ elements: ["div", "p", "script"] });
const customDoc = Document.parseHTMLUnsafe(html, { sanitizer });

⚖️ parseHTMLUnsafe vs parseHTML vs DOMParser

Examples Gallery

Examples follow MDN Document: parseHTMLUnsafe(). Use only trusted HTML in labs without a sanitizer. Never paste attacker-controlled strings.

const html = '<p>Hello</p><strong>Trusted markup</strong>';
const doc = Document.parseHTMLUnsafe(html);

console.log(doc.body.innerHTML);
// "<p>Hello</p><strong>Trusted markup</strong>"

<p>Hello</p><strong>Trusted markup</strong>

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

const unsafeDoc = Document.parseHTMLUnsafe(html);
const safeDoc = Document.parseHTML(html);

console.log({
  unsafe: unsafeDoc.body.innerHTML, // may include <script> node
  safe: safeDoc.body.innerHTML      // script removed
});

{ unsafe: "<p>Hi</p><script>...</script>", safe: "<p>Hi</p>" }

const html = '<p>Safe</p><script>alert(1)</script>';
const doc = Document.parseHTMLUnsafe(html, { sanitizer: "default" });

console.log(doc.body.innerHTML); // script stripped

<p>Safe</p>

const html = '<div><p>Hi</p><button>Go</button></div>';
const sanitizer = new Sanitizer({ elements: ["div", "p"] });

const doc = Document.parseHTMLUnsafe(html, { sanitizer });
console.log(doc.body.innerHTML); // button removed

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

function parseHtmlToDocument(html, { trusted = false } = {}) {
  if (!trusted && typeof Document.parseHTML === "function") {
    return Document.parseHTML(html);
  }
  if (typeof Document.parseHTMLUnsafe === "function") {
    return Document.parseHTMLUnsafe(
      html,
      trusted ? undefined : { sanitizer: "default" }
    );
  }
  return new DOMParser().parseFromString(html, "text/html");
}

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

OK

🚀 When This API Exists

• Declarative shadow DOM — parse HTML with <template shadowroot> into a Document (MDN).
• TrustedHTML pipelines — input already passed through a Trusted Types policy (MDN).
• Server-trusted fragments — CMS HTML you fully control (still audit carefully).
• Custom sanitizer allow-lists — when parseHTML() strips too aggressively.
• Not for raw user HTML — MDN: use parseHTML() or setHTML() instead.
• Preview Documents — inspect parsed trees before importing nodes into the live page.

📝 Notes

• Baseline 2025 on MDN — newly available since September 2025. Feature-detect on older browsers.
• Not Deprecated, Experimental, or Non-standard — defined in the HTML specification.
• Injection sink: no sanitizer by default; XSS risk with attacker-controlled strings (MDN).
• MDN: almost always prefer parseHTML() when supported for user HTML.
• Use TrustedHTML + require-trusted-types-for CSP to centralize sanitization audits (MDN).
• Related: parseHTML(), setHTML(), setHTMLUnsafe(), JavaScript hub.

💡 Best Practices