TheSanitizer interface of theHTML Sanitizer API defines a configuration object that specifies what elements, attributes and comments are allowed or should be removed when inserting strings of HTML into anElement orShadowRoot, or when parsing an HTML string into aDocument.

ASanitizer instance is effectively a wrapper around aSanitizerConfig, and can be passed as a configuration alternative in the samesanitization methods:

• setHTML() orsetHTMLUnsafe() onElement.
• setHTML() orsetHTMLUnsafe() onShadowRoot.
• Document.parseHTML() orDocument.parseHTMLUnsafe() static methods.

Note thatSanitizer is expected to be more efficient to reuse and modify when needed.

Constructors

Sanitizer()Experimental

Creates and returns aSanitizer object, optionally with custom sanitization behavior defined in aSanitizerConfig.

Instance methods

Sanitizer.allowElement()Experimental

Sets an element as allowed by the sanitizer, optionally with an array of attributes that are allowed or disallowed.

Sanitizer.get()Experimental

Returns the currentSanitizer configuration as aSanitizerConfig dictionary instance.

Sanitizer.removeElement()Experimental

Sets an element to be removed by the sanitizer.

Sanitizer.removeUnsafe()Experimental

Updates the sanitizer configuration so that it will remove any XSS-unsafe HTML.

Sanitizer.replaceElementWithChildren()Experimental

Sets an element to be replaced by its child HTML elements.

Sanitizer.allowAttribute()Experimental

Sets an attribute as allowed on any element.

Sanitizer.removeAttribute()Experimental

Sets an attribute to be removed from any element.

Sanitizer.setComments()Experimental

Sets whether comments will be allowed or removed by the sanitizer.

Sanitizer.setDataAttributes()Experimental

Sets whether data attributes on elements will be allowed or removed by the sanitizer.

Examples

For more examples see theHTML Sanitizer API and the individual methods.Below we show a few examples of how you might create different sanitizer configurations.

Creating a default sanitizer

The default sanitizer is constructed as shown below.

const sanitizer = new Sanitizer();

The XSS-safesanitization methods create the same sanitizer automatically if no options are passed.

Creating an empty sanitizer

To create an empty sanitizer, pass an empty object to the constructor.The resulting sanitizer configuration is shown below.

const sanitizer = new Sanitizer({});/*{  "attributes": [],  "comments": true,  "dataAttributes": true,  "elements": [],  "removeAttributes": [],  "removeElements": [],  "replaceWithChildrenElements": []}*/

Creating an "allow" sanitizer

This example shows how you might create an "allow sanitizer": a sanitizer that allows only a subset of attributes and elements.

The code first uses theSanitizer() constructor to create aSanitizer, specifying aSanitizerConfig that allows the element<div>,<p> and<script>.

The example then usesallowElement() to further allow<span> elements,allowAttribute() to allow theid attribute on any element, andreplaceElementWithChildren() method to set that any<b> elements should be replaced by their inner content (this is a kind of "allow" in that you are explicitly specifying some entities to keep).Lastly we specify that comments should be retained.

const sanitizer = new Sanitizer({ elements: ["div", "p", "script"] });sanitizer.allowElement("span");sanitizer.allowAttribute("id");sanitizer.replaceElementWithChildren("b");sanitizer.setComments(true);

Creating a "remove" sanitizer

This example shows how you might create a "remove sanitizer", specifying items to remove from the input.

The code first uses theSanitizer() constructor to create aSanitizer, specifying aSanitizerConfig that removes the element<span> and<script>.We then useremoveElement() to add<h6> to the array of elements to be removed, andremoveAttribute() to removelang from the attributes list. We also remove comments.

const sanitizer = new Sanitizer({ removeElements: ["span", "script"] });sanitizer.removeElement("h6");sanitizer.removeAttribute("lang");sanitizer.setComments(false);

Specifications

Browser compatibility