Document: parseHTMLUnsafe() static method

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.

A Document.

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".

The parseHTMLUnsafe() static method can be used to create a new Document instance, optionally filter out unwanted elements and attributes. The resulting Document will have a content type of "text/html", a character set of UTF-8, and a URL of "about:blank".

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. If no sanitizer configuration is specified in the options.sanitizer parameter, parseHTMLUnsafe() is used without any sanitization. Note that <script> elements are not evaluated during parsing.

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 <template> elements within that shadow root.

parseHTMLUnsafe() should be instead of Document.parseHTML() when parsing potentially unsafe strings of HTML that for whatever reason need to contain XSS-unsafe elements or attributes. If the HTML to be parsed doesn't need to contain unsafe HTML entities, then you should use Document.parseHTML().

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 HTML input will be passed through the trusted type transformation function before it is sanitized.

• Document.parseHTML()
• Element.setHTML() and Element.setHTMLUnsafe()
• ShadowRoot.setHTML() and ShadowRoot.setHTMLUnsafe()
• DOMParser.parseFromString() for parsing HTML or XML into a DOM tree
• HTML Sanitizer API