MCPcopy Create free account
hub / github.com/cure53/DOMPurify

github.com/cure53/DOMPurify

Chat with this repo
repository ↗ · DeepWiki ↗ · release 3.4.18 ↗ · + Follow · compare 9 versions
231 symbols 590 edges 37 files 24 documented · 10% ● updated 2d ago3.4.18 · 2026-11-14★ 17,5391 open issues

Browse by type

⨍ Functions 217◇ Types & classes 14
What it actually does AI analysis from the code graph — generated when you open this
loading…
README

DOMPurify

npm License Downloads dependents npm package minimized gzipped size (select exports) Cloudback

OpenSSF Best Practices Build & Test OpenSSF Scorecard Socket Badge snyk.io package health

DOMPurify is a DOM-only, super-fast, uber-tolerant XSS sanitizer for HTML, MathML and SVG.

It's also very simple to use and get started with. DOMPurify was started in February 2014 and, meanwhile, has reached version v3.4.18.

DOMPurify runs as JavaScript and works in all modern browsers (Safari (10+), Opera (15+), Edge, Firefox and Chrome - as well as almost anything else using Blink, Gecko or WebKit). It doesn't break on MSIE or other legacy browsers. It simply does nothing.

Note that DOMPurify v2.5.9 is the latest version supporting MSIE. For important security updates compatible with MSIE, please use the 2.x branch.

Our automated tests cover 9 browser/OS combinations on the current engines (Chromium, Firefox, and WebKit across Ubuntu, macOS, and Windows) on every push, and a separate matrix re-runs the suite on older engine snapshots (back to roughly Chromium 110, Firefox 108 and WebKit 16.4, around three years old) so regressions on outdated browsers get caught too. We also run Node.js v20, v22, v24, v25 and v26 with DOMPurify on jsdom. Older Node versions are known to work as well, but hey... no guarantees.

DOMPurify is written by security people who have vast background in web attacks and XSS. Fear not. For more details please also read about our Security Goals & Threat Model. Please, read it. Like, really. And if you enjoy the gory details, the Attack Classes & Bypass History page catalogs the parser-mutation, namespace, clobbering, and template tricks DOMPurify defends against.

The DOMPurify project inspired the creation of the HTML Sanitizer API, which is already shipping in many browsers. The same capability is now being standardized directly in the WHATWG HTML specification.

Table of Contents

What does it do?

DOMPurify sanitizes HTML and prevents XSS attacks. You can feed DOMPurify with e.g. a string full of dirty HTML and it will return a string (unless configured otherwise) with clean HTML. DOMPurify will strip out everything that contains dangerous HTML and thereby prevent XSS attacks and other nastiness. It's also damn bloody fast. We use the technologies the browser provides and turn them into an XSS filter. The faster your browser, the faster DOMPurify will be.

How do I use it?

It's easy. Just include DOMPurify on your website.

Using the unminified version (source-map available)

<script type="text/javascript" src="https://github.com/cure53/DOMPurify/raw/3.4.18/dist/purify.js"></script>

Using the minified and tested production version (source-map available)

<script type="text/javascript" src="https://github.com/cure53/DOMPurify/raw/3.4.18/dist/purify.min.js"></script>

Afterwards you can sanitize strings by executing the following code:

const clean = DOMPurify.sanitize(dirty);

Or maybe this, if you love working with Angular or alike:

import DOMPurify from 'dompurify';

const clean = DOMPurify.sanitize('<b>hello there</b>');

The resulting HTML can be written into a DOM element using innerHTML or the DOM using document.write(). That is fully up to you. Note that by default, we permit HTML, SVG and MathML. If you only need HTML, which might be a very common use-case, you can easily set that up as well:

const clean = DOMPurify.sanitize(dirty, { USE_PROFILES: { html: true } });

Is there any foot-gun potential?

Well, please note, if you first sanitize HTML and then modify it afterwards, you might easily void the effects of sanitization. If you feed the sanitized markup to another library after sanitization, please be certain that the library doesn't mess around with the HTML on its own. See the Security Goals & Threat Model for safe-usage recipes and the tags/attributes worth thinking twice about, and Attack Classes & Bypass History for why post-processing and changing the markup context defeat sanitization.

What about passing a DOM node instead of a string?

DOMPurify.sanitize() also accepts a DOM node (an Element, DocumentFragment or Document). Since 3.4.14 that path is hardened for nodes that did not come out of the HTML parser: a node built with the DOM API or parsed as XML/XHTML (for example via DOMParser with application/xhtml+xml and importNode()) can carry case-preserved attribute names such as ONERROR, or a rawtext element like <style> with an element child or its own end tag inside its text. Both shapes are invisible to a string sanitizer because the HTML parser can never build them, but they break out on reparse. DOMPurify now removes attributes by their exact Attr node and treats these literal-text trees as unsafe, so mixing document contexts on the input side is covered. It remains your job not to mix contexts on the output side, see the paragraph above.

One thing DOMPurify cannot sanitize is the content of a closed shadow root. Open shadow roots are walked, closed ones are invisible to any script, DOMPurify included. Markup can create one declaratively (<template shadowrootmode="closed">) when it goes through a parser that honors declarative shadow DOM, such as setHTMLUnsafe() or parseHTMLUnsafe(). So do not parse untrusted markup that way before handing the node to DOMPurify. This matters for IN_PLACE, RETURN_DOM and RETURN_DOM_FRAGMENT; string output never contains shadow roots, and string input is not affected.

Okay, makes sense, let's move on

After sanitizing your markup, you can also have a look at the property DOMPurify.removed and find out, what elements and attributes were thrown out. Please do not use this property for making any security critical decisions. This is just a little helper for curious minds.

Running DOMPurify on the server

DOMPurify technically also works server-side with Node.js. Our support strives to follow the Node.js release cycle.

Running DOMPurify on the server requires a DOM to be present, which is probably no surprise. Usually, jsdom is the tool of choice and we strongly recommend to use the latest version of jsdom.

Why? Because older versions of jsdom are known to be buggy in ways that result in XSS even if DOMPurify does everything 100% correctly. There are known attack vectors in, e.g. jsdom v19.0.0 that are fixed in jsdom v20.0.0 - and we really recommend to keep jsdom up to date because of that.

Please also be aware that tools like happy-dom exist but are not considered safe at this point. Combining DOMPurify with happy-dom is currently not recommended and will likely lead to XSS. For background on why the server-side DOM you choose is part of your trusted computing base, see Attack Classes & Bypass History.

On runtimes where jsdom cannot run, such as Cloudflare Workers or Vercel Edge, purify-edge is a third-party project that runs an unmodified DOMPurify on a parse5-based window. Our test suite can be run against it with npm run test:purify-edge as a compatibility check. It is not maintained by us, and a passing run is neither an endorsement nor a security guarantee.

Other than that, you are fine to use DOMPurify on the server. Probably. This really depends on jsdom or whatever DOM you utilize server-side. If you can live with that, this is how you get it to work:

npm install dompurify
npm install jsdom

For jsdom (please use an up-to-date version), this should do the trick:

const createDOMPurify = require('dompurify');
const { JSDOM } = require('jsdom');

const window = new JSDOM('').window;
const DOMPurify = createDOMPurify(window);
const clean = DOMPurify.sanitize('<b>hello there</b>');

Or even this, if you prefer working with imports:

import { JSDOM } from 'jsdom';
import DOMPurify from 'dompurify';

const window = new JSDOM('').window;
const purify = DOMPurify(window);
const clean = purify.sanitize('<b>hello there</b>');

If you have problems making it work in your specific setup, consider looking at the amazing isomorphic-dompurify project which solves lots of problems people might run into.

npm install isomorphic-dompurify
import DOMPurify from 'isomorphic-dompurify';

const clean = DOMPurify.sanitize('<s>hello</s>');

Is there a demo?

Of course there is a demo! Play with DOMPurify

What if I find a security bug?

First of all, please immediately contact us via email so we can work on a fix. PGP key

Also, you probably qualify for a bug bounty! The fine folks over at Fastmail use DOMPurify for their services and added our library to their bug bounty scope. So, if you find a way to bypass or weaken DOMPurify, please also have a look at their website and the bug bounty info.

Some purification samples please?

How does purified markup look like? Well, the demo shows it for a big bunch of nasty elements. But let's also show some smaller examples!

DOMPurify.sanitize('<img src=x onerror=alert(1)//>'); // becomes <img src="https://github.com/cure53/DOMPurify/raw/3.4.18/x">
DOMPurify.sanitize('<svg><g/onload=alert(2)//

'); // becomes <svg><g></g></svg>
DOMPurify.sanitize('

abc<iframe//src=jAva&Tab;script:alert(3)>def

'); // becomes 

abc


DOMPurify.sanitize('<math><mi//xlink:href="https://github.com/cure53/DOMPurify/raw/3.4.18/data:x,<script>alert(4)</script>">'); // becomes <math><mi></mi></math>
DOMPurify.sanitize('<TABLE><tr><td>HELLO</tr></TABL>'); // becomes <table><tbody><tr><td>HELLO</td></tr></tbody></table>
DOMPurify.sanitize('<UL><li><A HREF=//google.com>click</UL>'); // becomes <ul><li><a href="https://github.com/cure53/DOMPurify/raw/3.4.18/google.com">click</a></li></ul>

These are just a taste. For the full taxonomy of attack classes these samples come from - mutation XSS, namespace confusion, DOM clobbering, rawtext breakouts, and more - see Attack Classes & Bypass History.

What is supported?

DOMPurify currently supports HTML5, SVG and MathML. DOMPurify per default allows CSS, HTML custom data attributes. DOMPurify also supports the Shadow DOM - and sanitizes DOM templates recursively. That covers open shadow roots only: a closed shadow root cannot be read from script, so DOMPurify can neither see nor sanitize what is inside it. Strings are not affected, because DOMPurify's own parser ignores declarative shadow roots (<template shadowrootmode>), but setHTMLUnsafe() and Document.parseHTMLUnsafe() do not: if you parse untrusted markup with those and then pass the resulting nodes to DOMPurify (IN_PLACE, RETURN_DOM, RETURN_DOM_FRAGMENT), any closed shadow root in that markup comes back unsanitized. Pass untrus

Extension points exported contracts — how you extend this code

browse all types & interfaces →

Core symbols most depended-on inside this repo

browse all functions →

Shape

Function 203
Method 14
Interface 8
Class 6

Languages

TypeScript100%

Modules by API surface

src/purify.ts65 symbols
demos/lib/Mental.js60 symbols
test/test-suite.js28 symbols
test/bootstrap-test-suite.js14 symbols
src/types.ts14 symbols
src/utils.ts12 symbols
scripts/benchmark.js12 symbols
test/browser/legacy-runner.js8 symbols
typescript/verify.js5 symbols
scripts/fix-types.js3 symbols
test/fuzz/sanitize.fast-check.js2 symbols
test/browser/server.js2 symbols

Dependencies from manifests, versioned

@babel/core7.29.7 · 1×
@babel/preset-env7.29.7 · 1×
@babel/preset-typescript7.29.7 · 1×
@playwright/test1.61.0 · 1×
@rollup/plugin-babel7.1.0 · 1×
@types/estree1.0.9 · 1×
@types/node26.6.1 · 1×
cross-env10.1.0 · 1×
dompurifyfile:.. · 1×

For agents

$ claude mcp add DOMPurify \
  -- python -m otcore.mcp_server <graph>

⬇ download graph artifact

Ask about this repo answers extend the page