Element: setHTML() method

Experimental: This is an experimental technology
Check the Browser compatibility table carefully before using this in production.

The setHTML() method of the Element interface provides an XSS-safe method to parse and sanitize a string of HTML into a DocumentFragment, and then insert it into the DOM as a subtree of the element.

Syntax

setHTML(input)
setHTML(input, options)

Parameters

input

A string defining HTML to be sanitized and injected into the element.

options Optional

An options object with the following optional parameters:

sanitizer: A Sanitizer or SanitizerConfig object which defines what elements of the input will be allowed or removed, or the string "default" for the default configuration. Note that generally a "Sanitizer is expected to be more efficient than a SanitizerConfig if the configuration is to reused. If not specified, the default sanitizer configuration is used.

Return value

None (undefined).

Exceptions

TypeError

This is thrown if options.sanitizer is passed a:

non-normalized SanitizerConfig (one that includes both "allowed" and "removed" configuration settings).
string that does not have the value "default".
value that is not a Sanitizer, SanitizerConfig, or string.

Description

The setHTML() method provides an XSS-safe method to parse and sanitize a string of HTML into a DocumentFragment, and then insert it into the DOM as a subtree of the element.

setHTML() drops any elements in the HTML input string that are invalid in the context of the current element, such as a element outside of a

. It then removes any HTML entities that aren't allowed by the sanitizer configuration, and further removes any XSS-unsafe elements or attributes — whether or not they are allowed by the sanitizer configuration.

If no sanitizer configuration is specified in the options.sanitizer parameter, setHTML() is used with the default Sanitizer configuration. This configuration allows all elements and attributes that are considered XSS-safe, thereby disallowing entities that are considered unsafe. A custom sanitizer or sanitizer configuration can be specified to choose which elements, attributes, and comments are allowed or removed. Note that even if unsafe options are allowed by the sanitizer configuration, they will still be removed when using this method (which implicitly calls Sanitizer.removeUnsafe()).

setHTML() should be used instead of Element.innerHTML for inserting untrusted strings of HTML into an element. It should also be used instead of Element.setHTMLUnsafe(), unless there is a specific need to allow unsafe elements and attributes.

Note that since this method always sanitizes input strings of XSS-unsafe entities, it is not secured or validated using the Trusted Types API.

Examples

Basic usage

This example shows some of the ways you can use setHTML() to sanitize and inject a string of HTML.

// Define unsanitized string of HTML
const unsanitizedString = "abc