Baseline 2024
Newly available
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.
setHTMLUnsafe(input)
setHTMLUnsafe(input, options)
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.
None (undefined).
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:
Sanitizer, SanitizerConfig, or string.SanitizerConfig (one that includes both "allowed" and "removed" configuration settings)."default".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 <script> 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 <template> 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 usageThis example shows some of the ways you can use setHTMLUnsafe() to inject a string of HTML.
// Define unsanitized string of HTML
const unsanitizedString = "abc <script>alert(1)<" + "/script> def";
// Get the target Element with id "target"
const target = document.getElementById("target");
// setHTML() with no sanitizer
target.setHTMLUnsafe(unsanitizedString);
// Define custom Sanitizer and use in setHTMLUnsafe()
// This allows only elements: div, p, button, script
const sanitizer1 = new Sanitizer({
elements: ["div", "p", "button", "script"],
});
target.setHTML(unsanitizedString, { sanitizer: sanitizer1 });
// Define custom SanitizerConfig within setHTMLUnsafe()
// Removes the <script> element but allows other potentially unsafe entities.
target.setHTMLUnsafe(unsanitizedString, {
sanitizer: { removeElements: ["script"] },
});
setHTMLUnsafe() live example
This example provides a "live" demonstration of the method when called with different sanitizers. The code defines buttons that you can click to inject a string of HTML that is not sanitized, and that uses and a custom sanitizer, respectively. The original string and injected HTML are logged so you can inspect the results in each case.
HTMLThe HTML defines two <button> elements for calling the method with different sanitizers, another button to reset the example, and a <div> element to inject the string into.
<button id="buttonNoSanitizer" type="button">None</button>
<button id="buttonAllowScript" type="button">allowScript</button>
<button id="reload" type="button">Reload</button>
<div id="target">Original content of target element</div>
#log {
height: 240px;
overflow: scroll;
padding: 0.5rem;
border: 1px solid black;
margin: 5px;
}
const logElement = document.querySelector("#log");
function log(text) {
logElement.textContent += text;
}
if ("Sanitizer" in window) {
First we define the string to sanitize, which will be the same for all cases. This contains the <script> element and the onclick handler, both of which are considered XSS-unsafe. We also define the handler for the reload button.
// Define unsafe string of HTML
const unsanitizedString = `
<div>
<p>This is a paragraph. <button onclick="alert('You clicked the button!')">Click me</button></p>
<script src="path/to/a/module.js" type="module"><script>
</div>
`;
const reload = document.querySelector("#reload");
reload.addEventListener("click", () => document.location.reload());
Next we define the click handler for the button that sets the HTML with no sanitizer. Generally we would expect the method to drop elements in the string that aren't allowed in the context (such as table-specific elements in a <div> element), but otherwise match the input string. In this case the strings should match.
const buttonNoSanitizer = document.querySelector("#buttonNoSanitizer");
buttonNoSanitizer.addEventListener("click", () => {
// Set unsafe HTML without specifying a sanitizer
target.setHTMLUnsafe(unsanitizedString);
// Log HTML before sanitization and after being injected
logElement.textContent =
"No sanitizer: string should be injected without filtering\n\n";
log(`\nunsanitized: ${unsanitizedString}`);
log(`\nsanitized: ${target.innerHTML}`);
});
The next click handler sets the target HTML using a custom sanitizer that allows only <div>, <p>, and <script> elements. Note that because we're using the setHTMLUnsafe() method, <script> are not removed!
const allowScriptButton = document.querySelector("#buttonAllowScript");
allowScriptButton.addEventListener("click", () => {
// Set the content of the element using a custom sanitizer
const sanitizer1 = new Sanitizer({
elements: ["div", "p", "script"],
});
target.setHTMLUnsafe(unsanitizedString, { sanitizer: sanitizer1 });
// Log HTML before sanitization and after being injected
logElement.textContent = "Sanitizer: {elements: ['div', 'p', 'script']}\n";
log(`\nunsanitized: ${unsanitizedString}`);
log(`\nsanitized: ${target.innerHTML}`);
});
} else {
log("The HTML Sanitizer API is NOT supported in this browser.");
// Provide fallback or alternative behavior
}
Click the "None" and "allowScript" buttons to see the effects of no sanitizer and a custom sanitizer, respectively.
When you click the "None" button, you should see that the input and output match, as no sanitizer is applied. When you click the "allowScript" button the <script> element is still present, but the <button> element is removed. With this approach you can create safe HTML, but you aren't forced to.
RetroSearch is an open source project built by @garambo | Open a GitHub Issue
Search and Browse the WWW like it's 1997 | Search results from DuckDuckGo
HTML:
3.2
| Encoding:
UTF-8
| Version:
0.7.4