Sanitizer: Sanitizer() constructor

Experimental: This is an experimental technology
Check the Browser compatibility table carefully before using this in production.

The Sanitizer() constructor creates a new Sanitizer object, which can be used to filter unwanted elements and attributes from HTML or documents before they are inserted/parsed into the DOM.

The default Sanitizer() configuration allows only XSS-safe input by default, omitting elements such as <script>, <frame>, <iframe>, <object>, <use>, and event handler attributes from their respective allow lists, and disallowing data attributes, and comments.

The constructor configuration option can be used to customize the sanitizer behavior.

Syntax

js
new Sanitizer()
new Sanitizer(configuration)

Parameters

configuration Optional

A SanitizerConfig defining a sanitizer configuration, or the string "default" to indicate the default configuration.

Returns

An instance of the Sanitizer object.

Exceptions

TypeError

Thrown if a non-normalized SanitizerConfig is passed (one that includes both "allowed" and "removed" configuration settings), or if a string is passed that isn't "default".

Examples

Creating the default sanitizer

This example shows how you can create the default Sanitizer and logs the resulting configuration object.

JavaScript

The code first tests whether the Sanitizer interface is supported. It then creates the default Sanitizer, passing no options, and then gets and logs the configuration.

js
// Create default sanitizer
const sanitizer = new Sanitizer();

// Get and log the (default) configuration
const defaultConfig = sanitizer.get();
log(JSON.stringify(defaultConfig, null, 2));

Results

The output is logged below. Note that the default configuration is quite big, allowing many elements and attributes.

Creating a sanitizer and using it with setHTML()

This example shows how you might create and use a custom sanitizer in a safe HTML DOM insertion method.

HTML

Here we define two <pre> elements in which we'll display both the sanitized and unsanitized HTML.

html
<pre id="unmodified"></pre>
<pre id="setHTML"></pre>

JavaScript

The following code tests whether the Sanitizer interface is supported. It then defines a string of "unsafe HTML", which contains bot safe elements, such as <p> and <span>, and XSS-unsafe elements such as <script>

We then create a Sanitizer object with a SanitizerConfig that allows the HTML elements: <div>, <p>, <span>, and <script>. The sanitizer is used with the unsafe string in Element.setHTML(). Both the original and sanitized strings are displayed as text nodes.

js
// Define unsafe string of HTML
const unsafeHTMLString = `
  <div>
    <p>This is a paragraph. <span onclick="alert('You clicked the span!')">Click me</span></p>
    <script src="path/to/amodule.js" type="module"
  </div>
`;

// Set unsafe string as a text node of first element
const unmodifiedElement = document.querySelector("#unmodified");
unmodifiedElement.innerText = unsafeHTMLString;

// Create sanitizer using a SanitizerConfig that allows script (and other elements)
const sanitizer = new Sanitizer({ elements: ["div", "p", "span", "script"] });

// Use the sanitizer to set the HTML of the second element using the safe method
const setHTMLElement = document.querySelector("#setHTML");
setHTMLElement.setHTML(unsafeHTMLString, { sanitizer });

// Get that HTML and set it back to the element as a text node
// (so we can see the elements)
setHTMLElement.innerText = setHTMLElement.innerHTML;

// Log the configuration
const sanitizerConfig = sanitizer.get();
log(JSON.stringify(sanitizerConfig, null, 2));

Results

The original string and sanitized HTML that was parsed into the DOM are shown below. Note that even though the sanitizer allows <script> elements, these are stripped out of the injected HTML when using Element.setHTML(). Also note that the configuration includes both the names of the elements and their namespaces.

Specifications

Specification
HTML Sanitizer API
# dom-sanitizer-sanitizer

Browser compatibility