ShadowRoot: 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 ShadowRoot interface can be used to parse a string of HTML into a DocumentFragment, optionally filtering out unwanted elements and attributes, and then use it to replace the existing tree in the Shadow DOM.

Unlike with ShadowRoot.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:

html 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 can be used to parse a string of HTML, optionally filtering out unwanted elements and attributes, and use it to replace the existing Shadow 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