Element: setHTMLUnsafe() method
Baseline 2024Newly 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
orSanitizerConfig
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 aSanitizerConfig
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"
.
- value that is not a
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 elements, and script or event handler content attributes.
If no sanitizer configuration is specified in the
options.sanitizer
parameter, setHTMLUnsafe()
is used without any sanitization.
The input HTML may include declarative shadow roots.
If the string of HTML defines more than one declarative shadow root in a particular shadow host then only the first ShadowRoot
is created — subsequent declarations are parsed as elements within that shadow root.
Like setHTML()
, setHTMLUnsafe()
may be used instead of Element.innerHTML
in order to parse strings of HTML that may contain declarative shadow roots.
setHTMLUnsafe()
should be instead of Element.setHTML()
when parsing potentially unsafe strings of HTML that for whatever reason need to contain XSS-unsafe elements or attributes.
If strings to be injected don't need to contain unsafe HTML entities, then you should always use Element.setHTML()
.
Note that since this method does not necessarily sanitize input strings of XSS-unsafe entities, input strings should also be validated using the Trusted Types API. If the method is used with both a trusted types and a sanitizer, the input string will be passed through the trusted transformation function before it is sanitized.
Examples
Basic usage
This example shows some of the ways you can use setHTMLUnsafe()
to inject a string of HTML.
// Define unsanitized string of HTML
const unsanitizedString = "abc