Element: setHTMLUnsafe() method

Baseline 2024

Newly available

Since April 2024, this feature works across the latest devices and browser versions. This feature might not work in older devices or browsers.

The setHTMLUnsafe() method of the Element interface is used to parse a string of HTML into a DocumentFragment, optionally filtering out unwanted elements and attributes, and those that don't belong in the context, and then using it to replace the element's subtree in the DOM.

Unlike with Element.setHTML(), XSS-unsafe HTML entities are not guaranteed to be removed.

Syntax

setHTMLUnsafe(input)
setHTMLUnsafe(input, options)

Parameters

input

A string or TrustedHTML instance defining HTML to be parsed.

options Optional

An options object with the following optional parameters:

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

Return value

None (undefined).

Exceptions

TypeError

This is thrown if:

input is passed a string when Trusted Types are enforced by a CSP and no default policy is defined.
options.sanitizer is passed a:
- value that is not a Sanitizer, SanitizerConfig, or string.
- non-normalized SanitizerConfig (one that includes both "allowed" and "removed" configuration settings).
- string that does not have the value "default".

Description

The setHTMLUnsafe() method is used to parse a string of HTML into a DocumentFragment, optionally filtering out unwanted elements and attributes, and those that don't belong in the context, and then using it to replace the element's subtree in the DOM.

The suffix "Unsafe" in the method name indicates that while the method does allow the input string to be filtered of unwanted HTML entities, it does not enforce the sanitization or removal of potentially unsafe XSS-relevant input, such as