Using the HTML Sanitizer API

Safe sanitization by default

The most common use case for the API is to safely inject a user-provided string into an Element. Unless the string to be injected needs to contain unsafe HTML entities, you can use Element.setHTML() as a drop in replacement for Element.innerHTML.

For example, the following code will remove all XSS-unsafe elements and attributes in the input string (in this case the <script> element), along with any elements that aren't permitted as children of the target element by the HTML specification:

The other XSS-safe methods, ShadowRoot.setHTML() and Document.parseHTML(), are used in the same way.

Using a sanitizer configuration

All of the sanitization methods can be passed a Sanitizer or SanitizerConfig, which defines what elements, attributes and comments are either allowed, or should be removed, when inserting strings of HTML.

The Sanitizer is essentially a wrapper around a SanitizerConfig, performing some optimizations and normalizations that make it easier and safer to use, share and modify,

Using safe methods with a sanitizer

The XSS-safe methods always remove any unsafe HTML elements or attributes (as discussed in Safe sanitization by default above).

You can pass a sanitizer as the second argument to the safe methods to allow the same or fewer entities than the default configuration. For example, if you know that only <p> and <a> elements are expected in the context of someElement below, you might create a sanitizer configuration that allows only those elements:

Allowing unsafe sanitization

Sometimes you might want to inject input that needs to contain potentially unsafe elements or attributes. In this case you could use one of the API XSS-unsafe methods: Element.setHTMLUnsafe(), ShadowRoot.setHTMLUnsafe(), and Document.parseHTMLUnsafe().

To somewhat reduce the risk, you might first construct the default sanitizer, which only allows XSS-safe elements, and then allow just those unsafe entities that are expected in the input.

For example, in the following sanitizer all safe elements are allowed, and we further allow the unsafe onclick handler on button elements (only).

With this code the alert(1) would be allowed, and there is a potential issue that the attribute might be used for malicious purposes. However we know that all other XSS unsafe HTML entities have been removed, so we only need to worry about this one case, and can put in other mitigations.

The unsafe methods will use any sanitizer configuration you supply (or none), so you need to be careful when using them. Minimally you should enforce Trusted Types and pass TrustedHTML instead of strings into the methods.

Allow configurations

You can build an "allow" sanitizer configuration by specifying just the set of HTML elements and attributes you want to allow to be injected when using the sanitizer. This form of configuration is easy to understand, and is useful if you know exactly what HTML entities are should be permitted in the target context.

For example, the following configuration "allows" the <p> and <div> elements and attributes cite and onclick. It also replaces <b> elements with their contents (this is a form of "allowing", since the element contents are not removed).

Allowing elements

The allowed elements can be specified using the elements property of the SanitizerConfig instance passed to the Sanitizer() constructor (or directly to the sanitization methods).

The simplest way to use the property is to specify an array of element names:

But you can also specify each of the allowed elements using an object that defines its name and namespace, as shown below (Sanitizer will automatically infer a namespace if it is able).

You can also add the elements to a Sanitizer using Sanitizer.allowElement(). Here we add the same elements to an empty sanitizer:

Allowing global attributes

To allow attributes globally, on any element where allowed by the HTML specification, you can use the attributes property of the SanitizerConfig.

The simplest way to use the attributes property is to specify an array of attribute names:

You can also specify each attribute with the name and namespace properties, just like elements:

You can also add each of the allowed attributes to a Sanitizer using the Sanitizer.allowAttribute() method:

Allowing/removing attributes on a particular element

You can also allow or remove attributes on a particular element. Note that this is part of an "allow configuration", because you are in this case still allowing the element to be injected.

To allow an attribute on an element you can specify the element as an object with the name and attributes properties. The attributes property contains an array of the allowed attributes on the element.

Below we show a sanitizer where the <div>, <a>, and <span> elements are allowed, and the <a> element additionally allows the href, rel, hreflang and type attributes.

Similarly we can specify the attributes that are not allowed on an element using an element object with the removeAttributes property. For example, the following sanitizer would strip the type attribute from all <a> elements.

In both cases you can also specify each attribute as an object with name and namespace properties. You can also use set the attribute properties using the same element object passed to Sanitizer.allowElement().

Note that it is impossible to define per-element attribute behavior on a Sanitizer with a remove configuration, as the (needed) elements array is not present. Other restrictions on per-element attributes are covered in Valid configurations

Replacing child elements

You can specify an array of elements to replace with their inner content. This is most commonly used to strip styles from elements.

For example, the following code uses the replaceWithChildrenElements property of the SanitizerConfig to specify that the <b> element should be replaced:

As with elements and attributes, you can also specify the replacement elements with a namespace, or use the Sanitizer.replaceElementWithChildren() method:

Remove configurations

You can build a "remove" sanitizer configuration by specifying the set of HTML elements and attributes you want to remove from the input when using the sanitizer. All other elements and attributes are allowed by the configuration, although they may be removed if you use the configuration in a safe sanitization method.

For example, the following configuration removes the <script>, <div> and <span> elements and also the onclick attribute.

Specifying elements to remove is more useful when you want to tweak an existing configuration. For example consider the case where we are using the (safe) default sanitizer, but want to also ensure that some other elements are removed.

Removing elements

The removeElements property of a SanitizerConfig instance can be used the elements to remove.

The simplest way to use the property is to specify an array of element names:

As when allowing element you can also specify each of the elements to remove using an object that defines its name and namespace. You can also configure the removed elements using the using the Sanitizer API as shown:

Removing attributes

The removeElements property of the SanitizerConfig can be used to specify attributes to be globally removed.

The simplest way to use the property is to specify an array of element names:

You can also specify each of the elements using an object that defines its name and namespace, and also use Sanitizer.removeAttribute() to add an attribute to be removed from all elements.

Comments and data attributes

The SanitizerConfig can also be used to specify whether comments will be filtered from injected content, using the comments property, and whether data- attributes are allowed without having to add them to the attributes array using the dataAttributes boolean property.

To allow comments and all data-* attributes you might use a configuration like this:

You can similarly set the comments or data-attributes properties on an existing sanitizer using Sanitizer.setComments() and Sanitizer.setDataAttributes():

Sanitizer vs SanitizerConfig

All the sanitization methods can be passed a sanitizer configuration that is either a Sanitizer or SanitizerConfig instance.

The SanitizerConfig provides a compact method for specifying multiple elements or attributes that should be allowed or removed at the same time. Some care may be required when modifying this object to ensure that it remains a valid configuration.

The Sanitizer object is a wrapper around SanitizerConfig that provides additional useful functionality:

• The default constructor creates a configuration that allows all XSS-safe elements and attributes, and which is therefore a good starting point for creating either slightly more or slightly less restrictive sanitizers.
• The Sanitizer methods ensure that the underlying SanitizerConfig remains a valid configuration. For example, if you call allowElement() to allow an element then the element would also be removed from the underlying replaceWithChildrenElements array (if present). The normalizations make the configuration more efficient.
• The Sanitizer.removeUnsafe() method can be used to remove all XSS-unsafe entities from an existing configuration.
• You can export the configuration to see exactly what entities are allowed and dropped.

Note that if you can use the safe sanitization methods, then you may not need to define a sanitizer configuration at all.

Examples

For other examples see the HTML Sanitizer API and the individual methods of the Sanitizer interface.

Sanitizer demo

This example shows how you can use the Sanitizer methods to update a sanitizer. The result is a demonstration interface where you can add elements and attributes to the allow and remove lists and see their effects when the sanitizer is used with Element.setHTML() and Element.setHTMLUnsafe().

HTML

First we define buttons to reset the default sanitizer or an empty sanitizer.

This is followed by <select> elements to allow users to choose elements to add to the allow and remove lists for elements and attributes.

Then we add buttons to toggle comments and data attributes to be allowed/removed.

The remaining elements display the string to be parsed (editable) and the result of those two strings when injected into an element using setHTML() and setHMLUnsafe(), respectively:

JavaScript

The code first tests whether the Sanitizer interface is supported. It then defines a string of "unsafe HTML", which contains a mixture of XSS-safe and XSS-unsafe elements (such as <script>). This is inserted into the first text area as text. The text area is editable, so users can change the text later if they want.

We then get the elements for the setHTML and setHTMLUnsafe text areas where we will write the parsed HTML, and create an empty Sanitizer configuration. The applySanitizer() method is called with the new sanitizer to log the result of sanitizing the initial string using both a safe and unsafe sanitizer.

The applySanitizer() logging method is shown below. This gets the initial content of the "untrusted string" from the first text area, and parses it using the Element.setHTML() and Element.setHTMLUnsafe() methods with the passed sanitizer argument into the respective text areas. In each case the injected HTML is then read from the element with innerHTML and written back into the element as innerText (so that it is human readable).

The code then logs the current sanitizer configuration, which it obtains with Sanitizer.get().

Next we get elements for each of the buttons and selection lists.

The handlers for the first two button create the default and empty sanitizer respectively. The applySanitizer() method we showed before is used to run the sanitizer and update the logs.

The handlers for the selection lists are shown next. These call the associated sanitizer method on the current sanitizer whenever a new element or attribute is selected. For example, the listener for the allowElementSelect calls Sanitizer.allowElement() to add the selected element to the allowed elements. In each case, applySanitizer() logs the results using the current sanitizer.

The handlers for the last two buttons are shown below. These toggle the value of the dataAttributesActive and commentsActive variables and then use these values in Sanitizer.setComments() and Sanitizer.setDataAttributes() Note that if the comments are initially disabled, the first press of the button may have no effect!

Results

The result is shown below. Select the top buttons to set a new default or empty sanitizer, respectively. You can then use the selection lists to add some elements and attributes to the respective sanitizer allow and remove lists, and the other buttons to toggle comments on and off. The current sanitizer configuration is logged. The text in the top text area is sanitized using the current sanitizer configuration and parsed with setHTML() and setHTMLUnsafe().

Note that adding elements and attributes to the allow lists removes them from the remove lists, and vice versa. Also note that you can allow elements in sanitizer that will be injected with the unsafe methods, but not the safe methods.