TheparseHTMLUnsafe() static method of theDocument object is used to parse HTML input, optionally filtering unwanted HTML elements and attributes, in order to create a newDocument instance.

Syntax

Document.parseHTMLUnsafe(input)Document.parseHTMLUnsafe(input, options)

Parameters

input

ATrustedHTML or string instance defining HTML to be parsed.

optionsOptional

An options object with the following optional parameters:

sanitizerOptional

ASanitizer orSanitizerConfig object which defines what elements of the input will be allowed or removed.This can also be a string with the value"default", which applies aSanitizer with the default (XSS-safe) configuration.If not specified, no sanitizer is used.

Note that generally aSanitizer is expected than the to be more efficient than aSanitizerConfig if the configuration is to reused.

Return value

ADocument.

Exceptions

TypeError

This is thrown if:

• html is passed a string whenTrusted Types areenforced by a CSP and no default policy is defined.
• options.sanitizer is passed a:
  • value that is not aSanitizer,SanitizerConfig, or string.
  • non-normalizedSanitizerConfig (one that includes both "allowed" and "removed" configuration settings).
  • string that does not have the value"default".

Description

TheparseHTMLUnsafe() static method can be used to create a newDocument instance, optionally filter out unwanted elements and attributes.The resultingDocument will have acontent type of "text/html", acharacter set of UTF-8, and a URL of "about:blank".

The input HTML may includedeclarative shadow roots.If the string of HTML defines more than onedeclarative shadow root in a particular shadow host then only the firstShadowRoot is created — subsequent declarations are parsed as<template> elements within that shadow root.

parseHTMLUnsafe() doesn't perform any sanitization by default.If no sanitizer is passed as a parameter, all HTML entities in the input will be injected.

Security considerations

The suffix "Unsafe" in the method name indicates that it does not enforce removal of all XSS-unsafe HTML entities (unlikeDocument.parseHTML()).While it can do so if used with an appropriate sanitizer, it doesn't have to use an effective sanitizer, or any sanitizer at all!The method is therefore a possible vector forCross-site-scripting (XSS) attacks, where potentially unsafe strings provided by a user are injected into the DOM without first being sanitized.

You should mitigate this risk by always passingTrustedHTML objects instead of strings, andenforcing trusted type using therequire-trusted-types-for CSP directive.This ensures that the input is passed through a transformation function, which has the chance tosanitize the input to remove potentially dangerous markup (such as<script> elements and event handler attributes), before it is injected.

UsingTrustedHTML makes it possible to audit and check that sanitization code is effective in just a few places, rather than scattered across all your injection sinks.You should not need to pass a sanitizer to the method when usingTrustedHTML.

If for any reason you can't useTrustedHTML (or even better,setHTML()) then the next safest option is to usesetHTMLUnsafe() with the XSS-safe defaultSanitizer.

Specifications

Browser compatibility

See also

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