The Modern Native HTML Sanitizer API

Technical Deep Dive & Specifications

The Rich Text Dilemma

Modern web applications frequently need to allow users to format text with rich formatting:

• WYSIWYG editors (Notion, Google Docs, Slack).
• Markdown-to-HTML renderers.
• Community blogs supporting <b>, <i>, <ul>, <code>, and <blockquote>.

Assigning rich text via .textContent destroys all formatting tags, rendering raw HTML text. Assigning it via .innerHTML opens the door to XSS. Sanitization solves this dilemma by parsing the markup, stripping hazardous tags (<script>, <iframe>, <object>) and attributes (onload, onerror, onclick), and preserving only benign structural elements.

+-----------------------------------------------------------------------------------+
|                            HTML SANITIZATION LIFECYCLE                            |
+-----------------------------------------------------------------------------------+

   [DIRTY USER INPUT]
   `Hello <b>World</b><img src=x onerror=alert(1)>`
          |
          v
   [HTML SANITIZER ENGINE (Native setHTML() or DOMPurify)]
   1. Tokenizes string into an in-memory DocumentFragment.
   2. Traverses the node tree against an Allowlist.
   3. Drops forbidden nodes (<script>, <iframe>) and attributes (on*, javascript:).
   4. Preserves safe semantic nodes (<b>, <i>, <p>, <a>).
          |
          v
   [CLEAN DOM TREE]
   `Hello <b>World</b><img src="x">` (onerror attribute stripped)

The Menace of Mutation XSS (mXSS)

Mutation XSS (mXSS) occurs when an HTML string appears completely safe when evaluated by a JavaScript sanitization library, but is mutated into executable malicious code when the browser's live HTML parser parses and normalizes the DOM tree.

For example, subtle interactions between MathML (<math>), SVG (<svg>), and HTML foreign object boundaries can cause the browser parser to re-nest elements unexpectedly:

<!-- mXSS Vector: Looks like safe text inside math annotation -->
<form>
  <math>
    <mtext>
      </form><form>
      <mglyph>
        <style></math><img src=x onerror=alert(1)>

When a JavaScript-based sanitizer parses this, it may believe the <img> is trapped inside a non-rendered <style> or <math> container. But when serialized back to a string and assigned to innerHTML, the live browser engine closes the tags differently, exposing the <img onerror=alert(1)> in active HTML context.

The Native HTML Sanitizer API solves mXSS completely because it operates directly on the browser's live DOM tree, without round-tripping through string serialization.

The Native HTML Sanitizer API Specification

Standardized by the W3C and WHATWG Web Applications Working Group, the native Sanitizer API integrates directly with DOM elements:

1. Default Safe Usage with Element.setHTML()

// Automatically sanitizes using the browser's secure default allowlist
element.setHTML(untrustedHtmlString);

2. Custom Sanitizer Configuration

// Configure explicit element and attribute allowlists
const mySanitizer = new Sanitizer({
  allowElements: ['b', 'i', 'em', 'strong', 'a', 'p', 'ul', 'li', 'code'],
  blockElements: ['script', 'iframe', 'object', 'embed'],
  dropElements: ['style'], // dropElements removes element AND its children
  allowAttributes: {
    'href': ['a'],
    'title': ['*'],
    'class': ['*']
  }
});

// Apply custom sanitizer
element.setHTML(untrustedHtmlString, { sanitizer: mySanitizer });

DOMPurify: The Enterprise Industry Standard

Until native setHTML() reaches universal baseline support across all legacy runtimes, DOMPurify remains the gold standard:

import DOMPurify from 'dompurify';

// 1. Basic Sanitization
const cleanHtml = DOMPurify.sanitize(dirtyString);

// 2. Strict Custom Configuration
const strictClean = DOMPurify.sanitize(dirtyString, {
  ALLOWED_TAGS: ['b', 'i', 'strong', 'em', 'a', 'p', 'code', 'pre'],
  ALLOWED_ATTR: ['href', 'title', 'target'],
  ALLOW_DATA_ATTR: false,
  USE_PROFILES: { html: true, svg: false, mathMl: false } // Block SVG/MathML mXSS vectors
});

// 3. Post-Sanitization Hook (e.g. enforcing rel="noopener" on links)
DOMPurify.addHook('afterSanitizeAttributes', function (node) {
  if (node.tagName === 'A' && node.hasAttribute('target')) {
    node.setAttribute('rel', 'noopener noreferrer');
  }
});

Sanitization Approaches Compared

💻 Interactive Code Playground

Starter Code

The following example includes a client-side sanitizer laboratory comparing raw unsafe injection against DOMPurify-style safe sanitization.

Line-by-Line Code Breakdown

• Line 5: Imports the standard DOMPurify library.
• Line 47–51: Calls DOMPurify.sanitize() with an explicit ALLOWED_TAGS allowlist (p, strong, em, b, i, a, code) and ALLOWED_ATTR list.
• Line 49: Note that img and script are not in ALLOWED_TAGS, so they are automatically stripped. onerror is stripped as a hazardous event handler. href="javascript:..." is stripped because DOMPurify validates URI schemes automatically.
• Line 58: Feature-detects native setHTML support on Element.prototype.

Expected Browser Render Output

• The clean-output displays formatted text: "Welcome to Pro Web Dev!" and a clickable link to https://example.com.
• The broken <img onerror>, the javascript: link, and the <script> tag are completely stripped from the output.
• No alert() dialogs fire.