CharacterData: beforeHTML() method

Syntax

beforeHTML(input)
beforeHTML(input, options)

Parameters

input

A string defining HTML to be sanitized and inserted.

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, or the string "default" for the default configuration. The method will remove any XSS-unsafe elements and attributes, even if allowed by the sanitizer. If not specified, the default sanitizer configuration is used.

Note that if you're using the same configuration multiple times, it's expected to be more efficient to use a Sanitizer and modify it when you need to.

Return value

None (undefined).

Exceptions

TypeError

This is thrown if options.sanitizer is passed a:

• SanitizerConfig that isn't valid. For example, a configuration 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.

HierarchyRequestError DOMException

Thrown when the parent element is a Document, an <html> element, a <template> element, or a hostless DocumentFragment.

Description

beforeHTML() drops any elements in the HTML input string that are invalid in the context of the node's parent element (or the shadow host, if the parent is a shadow root), such as a <col> element outside of a <table>.

It then removes any HTML elements and attributes that aren't allowed by the sanitizer configuration, and further removes any XSS-unsafe elements or attributes — whether or not they are allowed by the sanitizer. For more information see the HTML Sanitizer API.

If no sanitizer is specified in the options.sanitizer parameter, beforeHTML() is used with the default sanitizer configuration. This configuration is suitable for the majority of use cases as it prevents XSS attacks, as well as other attacks like clickjacking or spoofing.

A custom Sanitizer or SanitizerConfig 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, they will still be removed when using this method (it removes the same elements as a sanitizer on which Sanitizer.removeUnsafe() has been called).

beforeHTML() can be used instead of Element.setHTML when HTML needs to be inserted before a text or comment node.

It should also be used instead of CharacterData.beforeHTMLUnsafe(), unless there is a specific need to allow unsafe elements and attributes.

Note that since this method always sanitizes input strings of XSS-unsafe entities, it is not secured or validated using the Trusted Types API.

Related HTML setter APIs

This is part of a series of APIs to set HTML in CharacterData:

Each API type takes the same arguments but allows for ease of inserting the required HTML in the appropriate place and with or without the default sanitizer applied. The unsafe variants allows scripts to be run using the runScripts options.

Similar methods, and more, exist on Element (for example Element.beforeHTML)

Examples

These examples shows some of the ways you can use beforeHTML() to sanitize and inject a string of HTML.

Basic usage with default sanitizer

Using the default sanitizer:

const unsanitizedString = "<p><i>abc</i><script>alert(1)<" + "/script> def</p>";
const myText = document.getElementById("myText").firstChild;

myText.beforeHTML(unsanitizedString);
// Result is that the following is added before the current text:
// <p><i>abc</i> def</p>

Using a custom sanitizer

Using a custom Sanitizer, that allows only the <div>, <p>, <button>, and <script> elements. Note that <script> is XSS-unsafe, so it will be removed anyway:

const unsanitizedString = "<p><i>abc</i><script>alert(1)<" + "/script> def</p>";
const myText = document.getElementById("myText").firstChild;

const mySanitizer = new Sanitizer({
  elements: ["div", "p", "button", "script"],
});
myText.beforeHTML(unsanitizedString, { sanitizer: mySanitizer });
// Result is that the following is added before the current text:
// <p> def</p>

Using a custom sanitizer with removeElements

Using a custom SanitizerConfig, that removes only the <div>, <p>, <button>, and <script> elements, as well as other XSS-unsafe elements and attributes that are always removed by this method.

const unsanitizedString = "<p><i>abc</i><script>alert(1)<" + "/script> def</p>";
const myText = document.getElementById("myText").firstChild;

myText.beforeHTML(unsanitizedString, {
  sanitizer: { removeElements: ["i", "script"] },
});
// Result is that the following is added before the current text:
// <p> def</p>

Specifications

Browser compatibility

See also

• CharacterData.beforeHTMLUnsafe()
• Element.beforeHTML() and Element.beforeHTMLUnsafe()
• Document.parseHTML() and Document.parseHTMLUnsafe()
• HTML Sanitizer API