Sanitizer

The Sanitizer interface of the HTML 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 an Element or ShadowRoot, or when parsing an HTML string into a Document.

A Sanitizer instance is effectively a wrapper around a SanitizerConfig, and can be passed as a configuration alternative in the same sanitization methods:

• setHTML() or setHTMLUnsafe() on Element.
• setHTML() or setHTMLUnsafe() on ShadowRoot.
• Document.parseHTML() or Document.parseHTMLUnsafe() static methods.

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

Constructors

Sanitizer() Experimental

Creates and returns a Sanitizer object, optionally with custom sanitization behavior defined in a SanitizerConfig.

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 current Sanitizer configuration as an SanitizerConfig 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 the HTML 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-safe sanitization 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 the Sanitizer() constructor to create a Sanitizer, specifying a SanitizerConfig that allows the element <div>, <p> and <script>.

The example then uses allowElement() to further allow <span> elements, allowAttribute() to allow the id attribute on any element, and replaceElementWithChildren() 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 the Sanitizer() constructor to create a Sanitizer, specifying a SanitizerConfig that removes the element <span> and <script>. We then use removeElement() to add <h6> to the array of elements to be removed, and removeAttribute() to remove lang 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