Document: parseHTML() static method
The parseHTML()
static method of the Document
object provides an XSS-safe method to parse and sanitize a string of HTML in order to create a new Document
instance.
Syntax
Document.parseHTML(input)
Document.parseHTML(input, options)
Parameters
input
A string defining HTML to be sanitized and injected into the shadow root.
options
OptionalAn options object with the following optional parameters:
sanitizer
A
Sanitizer
orSanitizerConfig
object which defines what elements of the input will be allowed or removed, or the string"default"
for the default sanitizer configuration. Note that generally a"Sanitizer
is expected to be more efficient than aSanitizerConfig
if the configuration is to reused. If not specified, the XSS-safe default sanitizer configuration is used.
Return value
A Document
.
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.
- non-normalized
Description
The parseHTML()
method parses and sanitize a string of HTML in order to create a new Document
instance that is XSS-safe. The resulting Document
will have a content type of "text/html", a character set of UTF-8, and a URL of "about:blank".
If no sanitizer configuration is specified in the options.sanitizer
parameter, parseHTML()
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()
).
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.
parseHTML()
should be used instead of Document.parseHTMLUnsafe()
, unless there is a specific need to allow unsafe elements and 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 always sanitizes input strings of XSS-unsafe entities, it is not secured or validated using the Trusted Types API.
Specifications
Specification |
---|
HTML Sanitizer API # dom-document-parsehtml |
Browser compatibility
See also
Document.parseHTMLUnsafe()
Element.setHTML()
andElement.setHTMLUnsafe()
ShadowRoot.setHTML()
andShadowRoot.setHTMLUnsafe()
DOMParser.parseFromString()
for parsing HTML or XML into a DOM tree- HTML Sanitizer API