Sanitizer: Sanitizer() constructor
Secure context: This feature is available only in secure contexts (HTTPS), in some or all supporting browsers.
Deprecated: This feature is no longer recommended. Though some browsers might still support it, it may have already been removed from the relevant web standards, may be in the process of being dropped, or may only be kept for compatibility purposes. Avoid using it, and update existing code if possible; see the compatibility table at the bottom of this page to guide your decision. Be aware that this feature may cease to work at any time.
The Sanitizer()
constructor creates a new Sanitizer
object, which can be used to sanitize untrusted strings of HTML, or untrusted Document
or DocumentFragment
objects, making them safe for insertion into a document's DOM.
The default Sanitizer()
configuration causes sanitizer operations to strip out XSS-relevant input by default, including <script>
tags, custom elements, and comments.
The constructor config
option can be used to customize the sanitizer behavior.
Syntax
new Sanitizer()
new Sanitizer(config)
Parameters
config
Optional-
A sanitizer configuration object with the following options (referred to as
SanitizerConfig
in the specification):allowElements
Optional-
An
Array
ofstrings
indicating elements that the sanitizer should not remove. All elements not in the array will be dropped. blockElements
Optional-
An
Array
ofstrings
indicating elements that the sanitizer should remove, but keeping their child elements. dropElements
Optional-
An
Array
ofstrings
indicating elements (including nested elements) that the sanitizer should remove. allowAttributes
Optional-
An
Object
where each key is the attribute name and the value is anArray
of allowed tag names. Matching attributes will not be removed. All attributes that are not in the array will be dropped. dropAttributes
Optional-
An
Object
where each key is the attribute name and the value is anArray
of dropped tag names. Matching attributes will be removed. allowCustomElements
Optional-
A
Boolean
value set tofalse
(default) to remove custom elements and their children. If set totrue
, custom elements will be subject to built-in and custom configuration checks (and will be retained or dropped based on those checks). allowComments
Optional-
A
Boolean
value set tofalse
(default) to remove HTML comments. Set totrue
in order to keep comments.
Note: allowElements
creates a sanitizer that will drop any elements that are not in allowElements
, while blockElements
and dropElements
create a sanitizer that will allow all elements except those in these properties.
blockElements
and dropElements
are processed before allowElements
.
If you specify both properties, the elements in blockElements
or dropElements
will be discarded first, followed by any elements not in allowElements
.
So while it is possible to specify both types of properties at the same time, the intent can always be more clearly captured using just one type.
The same applies to allowAttributes
and dropAttributes
.
Examples
The examples below show a sanitization operation using the Sanitizer.sanitize()
method.
Using the default sanitizer
This example shows how to sanitize data from an iframe with id userFrame
, using the Sanitizer.sanitize()
method:
const sanitizer = new Sanitizer(); // Default sanitizer;
// Get the frame and its Document object
const frame_element = document.getElementById("userFrame");
const unsanitized_frame_tree = frame_element.contentWindow.document;
// Sanitize the document tree and update the frame.
const sanitized_frame_tree = sanitizer.sanitize(unsanitized_frame_tree);
frame_element.replaceChildren(sanitized_frame_tree);
Specifications
Specification |
---|
HTML Sanitizer API # dom-sanitizer-sanitizer |
Browser compatibility
BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.