dompurify

↗ homepage

DOMPurify is a DOM-only, super-fast, uber-tolerant XSS sanitizer for HTML, MathML and SVG. It's written in JavaScript and works in all modern browsers (Safari, Opera (15+), Internet Explorer (10+), Firefox and Chrome - as well as almost anything else usin

weekly downloads24.2M

versionv3.3.1

license(MPL-2.0 OR Apache-2.0)

categoryutility

domxsshtmlsvgmathmlsecuritysecuresanitizersanitizefilterpurify

Overview

DOMPurify is a production-grade XSS sanitizer that cleans untrusted HTML, SVG, and MathML content before inserting it into the DOM. Unlike regex-based sanitizers, it uses native browser parsing APIs to detect and remove malicious code, making it both faster and more secure against sophisticated injection attacks. The library operates on a whitelist approach, stripping dangerous elements, attributes, and URI schemes while preserving legitimate content.

The package was created by Cure53, a security research firm, to address the inadequacy of regex-based sanitization methods that can be bypassed through encoding tricks, nested payloads, and browser quirks. With over 24 million weekly downloads, it's become the de facto standard for client-side sanitization in modern web applications. It runs in all modern browsers and server-side via Node.js with jsdom.

DOMPurify excels at handling edge cases that break other sanitizers: mXSS attacks, DOM clobbering, prototype pollution, and context-specific injections in SVG/MathML. It supports Shadow DOM sanitization, custom elements, and provides hooks for extending behavior. The library is configured via a simple options object passed to the sanitize() method, allowing developers to customize tag/attribute whitelists, return DOM nodes instead of strings, and add custom validation logic.

Developers choose DOMPurify when they need to display user-generated content, render markdown with raw HTML, integrate rich text editors, or handle any scenario where untrusted markup enters the application. Its minimal footprint (under 20KB minified) and zero runtime dependencies make it suitable for high-traffic sites and mobile applications where performance matters.

Quick Start

typescript

import DOMPurify from 'dompurify';

// Basic sanitization of user input
const userInput = '<img src=x onerror="alert(1)"><p>Safe content</p>';
const clean = DOMPurify.sanitize(userInput);
console.log(clean); // '<img src="x"><p>Safe content</p>'

// Custom configuration for blog posts
const blogPost = '<article><h2>Title</h2><script>evil()</script><iframe src="bad.com"></iframe></article>';
const safePost = DOMPurify.sanitize(blogPost, {
  ALLOWED_TAGS: ['article', 'h1', 'h2', 'h3', 'p', 'a', 'ul', 'ol', 'li', 'strong', 'em'],
  ALLOWED_ATTR: ['href', 'title', 'target'],
  KEEP_CONTENT: true
});

// Return DOM node for direct insertion
const fragment = DOMPurify.sanitize('<div>Content</div>', { RETURN_DOM_FRAGMENT: true });
document.getElementById('container').appendChild(fragment);

// Prevent DOM clobbering attacks
const userProfile = '<input name="username" id="admin">';
const safe = DOMPurify.sanitize(userProfile, {
  SANITIZE_NAMED_PROPS: true // Prefixes id/name with 'user-content-'
});

// Custom hook for URI validation
DOMPurify.addHook('afterSanitizeAttributes', (node) => {
  if (node.tagName === 'A') {
    const href = node.getAttribute('href');
    if (href && !href.match(/^https?:\/\//)) {
      node.removeAttribute('href');
    }
  }
});

const links = '<a href="javascript:alert(1)">Bad</a><a href="https://example.com">Good</a>';
const sanitized = DOMPurify.sanitize(links);
console.log(sanitized); // '<a>Bad</a><a href="https://example.com">Good</a>'

Use Cases

User-Generated Content: Sanitize forum posts, comments, or social media feeds that allow HTML formatting. DOMPurify removes <script> tags, event handlers, and dangerous attributes while preserving safe formatting like <b>, <i>, and <a> tags.

Rich Text Editors: Clean output from WYSIWYG editors (TinyMCE, CKEditor, Quill) before saving or displaying. Editors can generate invalid or malicious markup through copy-paste operations or bugs, and DOMPurify ensures only safe content reaches the DOM.

Markdown Rendering: Sanitize HTML output from markdown parsers that allow raw HTML blocks. Many markdown processors pass through HTML unchanged, creating XSS vulnerabilities if the source is untrusted.

Email Content Display: Render HTML emails in webmail clients safely. Email HTML often contains tracking pixels, phishing links, and embedded scripts that need removal while maintaining layout and styling.

API Response Rendering: Clean HTML returned from third-party APIs or CMS systems before injecting into your application. Even trusted APIs can be compromised or contain user-contributed content that hasn't been properly sanitized.

Pros & Cons

Pros

+DOM-based parsing prevents bypass attacks that defeat regex sanitizers, using the browser's own HTML parser to detect malicious patterns
+Comprehensive coverage of HTML5, SVG, MathML, and Shadow DOM with protection against DOM clobbering and mXSS attacks
+Highly configurable with whitelist/blacklist options, custom hooks, and multiple return formats (string, DOM node, DocumentFragment)
+Zero dependencies and small footprint (~19KB minified) with excellent performance using native browser APIs
+Battle-tested security maintained by Cure53 with active updates for emerging attack vectors

Cons

−Requires jsdom as a peer dependency for Node.js environments, adding ~2MB to server-side bundles
−Default configuration may be too restrictive for some use cases, requiring manual whitelist additions for custom elements or data attributes
−Cannot sanitize JavaScript objects or JSON payloads—only works with markup strings, not protecting against non-DOM injection vectors

Alternatives

xssv1.0.15

Sanitize untrusted HTML (to prevent XSS) with a configuration specified by a Whitelist

utilitysanitizationxss

3.5M / week

Comparisons

dompurify vs xss

utility

Install

bash

npm install dompurify

bash

pnpm add dompurify

bash

bun add dompurify

Overview

Quick Start

typescript

import DOMPurify from 'dompurify';

// Basic sanitization of user input
const userInput = '<img src=x onerror="alert(1)"><p>Safe content</p>';
const clean = DOMPurify.sanitize(userInput);
console.log(clean); // '<img src="x"><p>Safe content</p>'

// Custom configuration for blog posts
const blogPost = '<article><h2>Title</h2><script>evil()</script><iframe src="bad.com"></iframe></article>';
const safePost = DOMPurify.sanitize(blogPost, {
  ALLOWED_TAGS: ['article', 'h1', 'h2', 'h3', 'p', 'a', 'ul', 'ol', 'li', 'strong', 'em'],
  ALLOWED_ATTR: ['href', 'title', 'target'],
  KEEP_CONTENT: true
});

// Return DOM node for direct insertion
const fragment = DOMPurify.sanitize('<div>Content</div>', { RETURN_DOM_FRAGMENT: true });
document.getElementById('container').appendChild(fragment);

// Prevent DOM clobbering attacks
const userProfile = '<input name="username" id="admin">';
const safe = DOMPurify.sanitize(userProfile, {
  SANITIZE_NAMED_PROPS: true // Prefixes id/name with 'user-content-'
});

// Custom hook for URI validation
DOMPurify.addHook('afterSanitizeAttributes', (node) => {
  if (node.tagName === 'A') {
    const href = node.getAttribute('href');
    if (href && !href.match(/^https?:\/\//)) {
      node.removeAttribute('href');
    }
  }
});

const links = '<a href="javascript:alert(1)">Bad</a><a href="https://example.com">Good</a>';
const sanitized = DOMPurify.sanitize(links);
console.log(sanitized); // '<a>Bad</a><a href="https://example.com">Good</a>'

Use Cases

Pros & Cons

Pros

+DOM-based parsing prevents bypass attacks that defeat regex sanitizers, using the browser's own HTML parser to detect malicious patterns
+Comprehensive coverage of HTML5, SVG, MathML, and Shadow DOM with protection against DOM clobbering and mXSS attacks
+Highly configurable with whitelist/blacklist options, custom hooks, and multiple return formats (string, DOM node, DocumentFragment)
+Zero dependencies and small footprint (~19KB minified) with excellent performance using native browser APIs
+Battle-tested security maintained by Cure53 with active updates for emerging attack vectors

Cons

−Requires jsdom as a peer dependency for Node.js environments, adding ~2MB to server-side bundles
−Default configuration may be too restrictive for some use cases, requiring manual whitelist additions for custom elements or data attributes
−Cannot sanitize JavaScript objects or JSON payloads—only works with markup strings, not protecting against non-DOM injection vectors