DOMPurify Documentation

security

<script type="text/javascript" src="dist/purify.js"></script>
<script type="text/javascript" src="dist/purify.min.js"></script>
const clean = DOMPurify.sanitize(dirty);
import DOMPurify from 'dompurify';

const clean = DOMPurify.sanitize('<b>hello there</b>');
const clean = DOMPurify.sanitize(dirty, { USE_PROFILES: { html: true } });
npm install dompurify
npm install jsdom
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>');
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>');
npm install isomorphic-dompurify
import DOMPurify from 'isomorphic-dompurify';

const clean = DOMPurify.sanitize('<s>hello</s>');
DOMPurify.sanitize('<img src=x onerror=alert(1)//>'); // becomes <img src="x">
DOMPurify.sanitize('<svg><g/onload=alert(2)//<p>'); // becomes <svg><g></g></svg>
DOMPurify.sanitize('<p>abc<iframe//src=jAva&Tab;script:alert(3)>def</p>'); // becomes <p>abc</p>
DOMPurify.sanitize('<math><mi//xlink:href="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="//google.com">click</a></li></ul>
window.trustedTypes.createPolicy('default', {
  createHTML: (to_escape) =>
    DOMPurify.sanitize(to_escape, { RETURN_TRUSTED_TYPE: false }),
});
window.trustedTypes.createPolicy('my-organization', {
  createHTML: (input) =>
    DOMPurify.sanitize(input, { TRUSTED_TYPES_POLICY: null }),
});
// strip {{ ... }}, ${ ... } and <% ... %> to make output safe for template systems
// be careful please, this mode is not recommended for production usage.
// allowing template parsing in user-controlled HTML is not advised at all.
// only use this mode if there is really no alternative.
const clean = DOMPurify.sanitize(dirty, { SAFE_FOR_TEMPLATES: true });

// change how e.g. comments containing risky HTML characters are treated.
// be very careful, this setting should only be set to `false` if you really only handle
// HTML and nothing else, no SVG, MathML or the like.
// Otherwise, changing from `true` to `false` will lead to XSS in this or some other way.
const clean = DOMPurify.sanitize(dirty, { SAFE_FOR_XML: false });
/* Detailed source-code truncated for AI context efficiency. */
/* Detailed source-code truncated for AI context efficiency. */
// extend the existing array of elements that can use Data URIs
const clean = DOMPurify.sanitize(dirty, { ADD_DATA_URI_TAGS: ['a', 'area'] });

// extend the existing array of elements that are safe for URI-like values (be careful, XSS risk)
const clean = DOMPurify.sanitize(dirty, { ADD_URI_SAFE_ATTR: ['my-attr'] });
// allow external protocol handlers in URL attributes (default is false, be careful, XSS risk)
// by default only http, https, ftp, ftps, tel, mailto, callto, sms, cid, xmpp and matrix are allowed.
const clean = DOMPurify.sanitize(dirty, { ALLOW_UNKNOWN_PROTOCOLS: true });

// allow specific protocol handlers in URL attributes via regex (default is false, be careful, XSS risk)
// by default only (protocol-)relative URLs, http, https, ftp, ftps, tel, mailto, callto, sms, cid, xmpp and matrix are allowed.
// Default RegExp: /^(?:(?:(?:f|ht)tps?|mailto|tel|callto|sms|cid|xmpp|matrix):|[^a-z]|[a-z+.\-]+(?:[^a-z+.\-:]|$))/i;
// The example below extends the default with one additional scheme (sftp).
// Keep the pattern linear-time: it runs against attacker-controlled values.
const clean = DOMPurify.sanitize(dirty, {
  ALLOWED_URI_REGEXP:
    /^(?:(?:(?:f|ht)tps?|sftp|mailto|tel|callto|sms|cid|xmpp|matrix):|[^a-z]|[a-z+.\-]+(?:[^a-z+.\-:]|$))/i,
});
// return a DOM HTMLBodyElement instead of an HTML string (default is false)
const clean = DOMPurify.sanitize(dirty, { RETURN_DOM: true });

// return a DOM DocumentFragment instead of an HTML string (default is false)
const clean = DOMPurify.sanitize(dirty, { RETURN_DOM_FRAGMENT: true });

// use the RETURN_TRUSTED_TYPE flag to turn on Trusted Types support if available
const clean = DOMPurify.sanitize(dirty, { RETURN_TRUSTED_TYPE: true }); // will return a TrustedHTML object instead of a string if possible

// use a provided Trusted Types policy
const clean = DOMPurify.sanitize(dirty, {
  // supplied policy must define createHTML and createScriptURL
  TRUSTED_TYPES_POLICY: trustedTypes.createPolicy('dompurify', {
    createHTML(s) {
      return s;
    },
    createScriptURL(s) {
      return s;
    },
  }),
});

// opt out of DOMPurify's internal `dompurify` Trusted Types policy entirely
// (useful when your CSP `trusted-types` allowlist does not include `dompurify`)
const clean = DOMPurify.sanitize(dirty, { TRUSTED_TYPES_POLICY: null });
/* Detailed source-code truncated for AI context efficiency. */
// use the IN_PLACE mode to sanitize a node "in place", which is much faster depending on how you use DOMPurify
const dirty = document.createElement('a');
dirty.setAttribute('href', 'javascript:alert(1)');

const clean = DOMPurify.sanitize(dirty, { IN_PLACE: true }); // see https://github.com/cure53/DOMPurify/issues/288 for more info
DOMPurify.addHook(
  'uponSanitizeAttribute',
  function (currentNode, hookEvent, config) {
    // Do something with the current node
    // You can also mutate hookEvent for current node (i.e. set hookEvent.forceKeepAttr = true)
    // For other than 'uponSanitizeAttribute' hook types hookEvent equals to null
  }
);
// Clean HTML string and write into our DIV
const clean = DOMPurify.sanitize(dirty);
// Specify a configuration directive, only <P> elements allowed
// Note: We want to also keep <p>'s text content, so we add #text too
const config = { ALLOWED_TAGS: ['p', '#text'], KEEP_CONTENT: false };

// Clean HTML string and write into our DIV
const clean = DOMPurify.sanitize(dirty, config);
// Specify a configuration directive
const config = {
  ALLOWED_TAGS: ['p', '#text'], // only <P> and text nodes
  KEEP_CONTENT: false, // remove content from non-allow-listed nodes too
  ADD_ATTR: ['kitty-litter'], // permit kitty-litter attributes
  ADD_TAGS: ['ying', 'yang'], // permit additional custom tags
  RETURN_DOM: true, // return a document object instead of a string
};

// Clean HTML string and write into our DIV
const clean = DOMPurify.sanitize(dirty, config);
// Add a hook to convert all text to capitals
DOMPurify.addHook('beforeSanitizeAttributes', function (node) {
  // Set text node content to uppercase
  if (node.nodeName && node.nodeName === '#text') {
    node.textContent = node.textContent.toUpperCase();
  }
});

// Clean HTML string and write into our DIV
const clean = DOMPurify.sanitize(dirty);
// Add a hook to convert all text to capitals
DOMPurify.addHook('beforeSanitizeAttributes', function (node) {
  // Set text node content to uppercase
  if (node.nodeName && node.nodeName === '#text') {
    node.textContent = node.textContent.toUpperCase();
  }
});

// Clean HTML string and write into our DIV
let clean = DOMPurify.sanitize(dirty);

// now let's remove the hook again
console.log(DOMPurify.removeHook('beforeSanitizeAttributes'));

// Clean HTML string and write into our DIV
let clean = DOMPurify.sanitize(dirty);
DOMPurify.addHook('uponSanitizeElement', (node) => {
  if (!node.hasChildNodes() && !node.textContent) {
    node.remove();
  }
});
DOMPurify.setConfig({ ALLOWED_TAGS: ['div', '#text', 'footer'] });

DOMPurify.addHook('uponSanitizeElement', (node) => {
  if (node.tagName === 'FOOTER') {
    node.remove();
  }
});
// Add a hook to make all links open a new window
DOMPurify.addHook('afterSanitizeAttributes', function (node) {
  // set all elements owning target to target=_blank
  if ('target' in node) {
    node.setAttribute('target', '_blank');
  }
  // set non-HTML/MathML links to xlink:show=new
  if (
    !node.hasAttribute('target') &&
    (node.hasAttribute('xlink:href') || node.hasAttribute('href'))
  ) {
    node.setAttribute('xlink:show', 'new');
  }
});

// Clean HTML string and write into our DIV
const clean = DOMPurify.sanitize(dirty);
// allowed URI schemes
const allowlist = ['http', 'https', 'ftp'];

// build fitting regex
const regex = RegExp('^(' + allowlist.join('|') + '):', 'gim');

// Add a hook to enforce URI scheme allow-list
DOMPurify.addHook('afterSanitizeAttributes', function (node) {
  // build an anchor to map URLs to
  const anchor = document.createElement('a');

  // check all href attributes for validity
  if (node.hasAttribute('href')) {
    anchor.href = node.getAttribute('href');
    if (anchor.protocol && !anchor.protocol.match(regex)) {
      node.removeAttribute('href');
    }
  }
  // check all action attributes for validity
  if (node.hasAttribute('action')) {
    anchor.href = node.getAttribute('action');
    if (anchor.protocol && !anchor.protocol.match(regex)) {
      node.removeAttribute('action');
    }
  }
  // check all xlink:href attributes for validity
  if (node.hasAttribute('xlink:href')) {
    anchor.href = node.getAttribute('xlink:href');
    if (anchor.protocol && !anchor.protocol.match(regex)) {
      node.removeAttribute('xlink:href');
    }
  }
});

// Clean HTML string and write into our DIV
const clean = DOMPurify.sanitize(dirty);
// allow script elements
const config = {
  ADD_TAGS: ['script'],
  ADD_ATTR: ['onclick', 'onmouseover', 'onload', 'onunload'],
};

// Add a hook to sanitize all script content with MentalJS
DOMPurify.addHook('uponSanitizeElement', function (node, data) {
  if (data.tagName === 'script') {
    let script = node.textContent;
    if (
      !script ||
      'src' in node.attributes ||
      'href' in node.attributes ||
      'xlink:href' in node.attributes
    ) {
      return node.parentNode.removeChild(node);
    }
    try {
      let mental = MentalJS().parse({
        options: {
          eval: false,
          dom: true,
        },
        code: script,
      });
      return (node.textContent = mental);
    } catch (e) {
      return node.parentNode.removeChild(node);
    }
  }
});

// Add a hook to sanitize all white-listed events with MentalJS
DOMPurify.addHook('uponSanitizeAttribute', function (node, data) {
  if (data.attrName.match(/^on\w+/)) {
    let script = data.attrValue;
    try {
      return (data.attrValue = MentalJS().parse({
        options: {
          eval: false,
          dom: true,
        },
        code: script,
      }));
    } catch (e) {
      return (data.attrValue = '');
    }
  }
});

// Clean HTML string and write into our DIV
const clean = DOMPurify.sanitize(dirty, config);
// Add a hook to make all links point to a proxy
DOMPurify.addHook('afterSanitizeAttributes', function (node) {
  // proxy form actions
  if ('action' in node) {
    node.setAttribute(
      'action',
      proxy + encodeURIComponent(node.getAttribute('action'))
    );
  }
  // proxy regular HTML links
  if (node.hasAttribute('href')) {
    node.setAttribute(
      'href',
      proxy + encodeURIComponent(node.getAttribute('href'))
    );
  }
  // proxy SVG/MathML links
  if (node.hasAttribute('xlink:href')) {
    node.setAttribute(
      'xlink:href',
      proxy + encodeURIComponent(node.getAttribute('xlink:href'))
    );
  }
});

// Clean HTML string and write into our DIV
const clean = DOMPurify.sanitize(dirty);
/* Detailed source-code truncated for AI context efficiency. */
// Add a hook to post-process the sanitized SVG root: re-add the
// namespaces (added by tools like Illustrator, stripped during
// sanitization) that an <img>-embedded SVG needs to render
DOMPurify.addHook('afterSanitizeAttributes', function (node) {
  if (node.tagName && node.tagName.toLowerCase() === 'svg') {
    node.setAttribute('xmlns', 'http://www.w3.org/2000/svg');
    node.setAttribute('xmlns:xlink', 'http://www.w3.org/1999/xlink');
  }
});

// Clean the SVG string and allow the "filter" tag
const clean = DOMPurify.sanitize(dirty, { ADD_TAGS: ['filter'] });

// Show the sanitized content in an <img> element
const img = new Image();
img.src = 'data:image/svg+xml;base64,' + window.btoa(clean);
document.getElementById('sanitized').appendChild(img);

Technical Documentation: cure53/DOMPurify

Overview (`README.md`) Copy Section

DOMPurify

Table of Contents Copy Chapter

What does it do? Copy Chapter

How do I use it? Copy Chapter

Using the unminified version (source-map available) Copy Section

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

Is there any foot-gun potential? Copy Section

What about passing a DOM node instead of a string? Copy Section

Okay, makes sense, let's move on Copy Section

Running DOMPurify on the server Copy Section

Is there a demo? Copy Chapter

What if I find a security bug? Copy Chapter

Some purification samples please? Copy Chapter

What is supported? Copy Chapter

What about legacy browsers like Internet Explorer? Copy Chapter

What about DOMPurify and Trusted Types? Copy Chapter

Can I configure DOMPurify? Copy Chapter

General settings Copy Section

Control our allow-lists and block-lists Copy Section

Control behavior relating to Custom Elements Copy Section

Control behavior relating to URI values Copy Section

Control permitted attribute values Copy Section

Influence the return-type Copy Section

Influence how we sanitize Copy Section

Influence where we sanitize Copy Section

Persistent Configuration Copy Chapter

Hooks Copy Chapter

Hook behavior worth knowing Copy Section

A note on calling `sanitize()` from a hook Copy Section

Removed Configuration Copy Chapter

Continuous Integration Copy Chapter

Development and contributing Copy Section

Installation (`npm i`)

Scripts

Security Mailing List Copy Chapter

Who contributed? Copy Chapter

Overview (`demos/README.md`) Copy Section

What is this? Copy Chapter

Basic Demo [Link](basic-demo.html) Copy Section

Config Demo [Link](config-demo.html) Copy Section

Advanced Config Demo [Link](advanced-config-demo.html) Copy Section

Hooks Demo [Link](hooks-demo.html) Copy Section

Add hooks and remove hooks [Link](hooks-removal-demo.html) Copy Section

Hook to remove empty elements [Link](hooks-node-removal-demo.html) Copy Section

Hook to remove an element and its content [Link](hooks-node-removal2-demo.html) Copy Section

Hook to sanitize CSS [Link](hooks-sanitize-css-demo.html) Copy Section

Trusted Types demo [Link](trusted-types-demo.html) Copy Section

Hook to open all links in a new window [Link](hooks-target-blank-demo.html) Copy Section

Hook to white-list safe URI Schemes [Link](hooks-scheme-allowlist.html) Copy Section

Hook to allow and sand-box all JavaScript [Link](hooks-mentaljs-demo.html) Copy Section

Hook to proxy all links [Link](hooks-link-proxy-demo.html) Copy Section

Hook to proxy all HTTP leaks including CSS [Link](hooks-proxy-demo.html) Copy Section

Hook to sanitize SVGs shown via an `` tag. [Link](hooks-svg-demo.html) Copy Section

Overview (`typescript/commonjs-with-no-types/types/readme.md`) Copy Section

Overview (`typescript/esm-with-no-types/types/readme.md`) Copy Section

Explore Related Technologies & Topics

Overview (`README.md`)

Table of Contents

What does it do?

How do I use it?

Using the unminified version (source-map available)

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

Is there any foot-gun potential?

What about passing a DOM node instead of a string?

Okay, makes sense, let's move on

Running DOMPurify on the server

Is there a demo?

What if I find a security bug?

Some purification samples please?

What is supported?

What about legacy browsers like Internet Explorer?

What about DOMPurify and Trusted Types?

Can I configure DOMPurify?

General settings

Control our allow-lists and block-lists

Control behavior relating to Custom Elements

Control behavior relating to URI values

Control permitted attribute values

Influence the return-type

Influence how we sanitize

Influence where we sanitize

Persistent Configuration

Hooks

Hook behavior worth knowing

A note on calling `sanitize()` from a hook

Removed Configuration

Continuous Integration

Development and contributing

Security Mailing List

Who contributed?

Overview (`demos/README.md`)

What is this?

Basic Demo [Link](basic-demo.html)

Config Demo [Link](config-demo.html)

Advanced Config Demo [Link](advanced-config-demo.html)

Hooks Demo [Link](hooks-demo.html)

Add hooks and remove hooks [Link](hooks-removal-demo.html)

Hook to remove empty elements [Link](hooks-node-removal-demo.html)

Hook to remove an element and its content [Link](hooks-node-removal2-demo.html)

Hook to sanitize CSS [Link](hooks-sanitize-css-demo.html)

Trusted Types demo [Link](trusted-types-demo.html)

Hook to open all links in a new window [Link](hooks-target-blank-demo.html)

Hook to white-list safe URI Schemes [Link](hooks-scheme-allowlist.html)

Hook to allow and sand-box all JavaScript [Link](hooks-mentaljs-demo.html)

Hook to proxy all links [Link](hooks-link-proxy-demo.html)

Hook to proxy all HTTP leaks including CSS [Link](hooks-proxy-demo.html)

Hook to sanitize SVGs shown via an `` tag. [Link](hooks-svg-demo.html)

Overview (`typescript/commonjs-with-no-types/types/readme.md`)

Overview (`typescript/esm-with-no-types/types/readme.md`)