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
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.
// 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.
<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.
// 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 |