Sanitizer: allowElement() method

element

A string indicating the name of the allowed element, or an object with the following properties:

name

A string containing the name of the element.

namespace Optional

A string containing the namespace of the element. The default namespace is "http://www.w3.org/1999/xhtml".

attributes Optional

An array indicating the attributes to allow on this (allowed) element when sanitizing HTML.

Each attribute can be specified by name (a string), or as a object with the following properties:

name

A string containing the name of the attribute.

namespace Optional

A string containing the namespace of the attribute, which defaults to null.

removeAttributes Optional

An array indicating the attributes to remove on this (allowed) element when sanitizing HTML.

Each attribute can be specified by name (a string), or as a object with the following properties:

name

A string containing the name of the attribute.

namespace Optional

A string containing the namespace of the attribute, which defaults to null.

None (undefined).

This example shows how allowElement() is used to add an element to the sanitizer's elements configuration (the list of allowed elements).

<pre id="log"></pre>

#log {
  height: 400px;
  overflow: scroll;
  padding: 0.5rem;
  border: 1px solid black;
}

const logElement = document.querySelector("#log");
function log(text) {
  logElement.textContent = text;
}

JavaScript

The code first creates a new Sanitizer object that initially allows <div> and <script> elements. It then calls allowElement() to add a <p> element specified as a string parameter, and then again to add a <span> element specified as an object. We then get and log the configuration.

if ("Sanitizer" in window) {

// Create sanitizer using SanitizerConfig
const sanitizer = new Sanitizer({
  elements: ["div", "script"],
});

// Allow <p> specifying an string
sanitizer.allowElement("p");

// Allow <span> specifying an object
sanitizer.allowElement({ name: "span" });

let sanitizerConfig = sanitizer.get();
log(JSON.stringify(sanitizerConfig, null, 2));

} else {
  log("The HTML Sanitizer API is NOT supported in this browser.");
}

Results

The final configuration is logged below. This includes the original elements (<div> and <script>) and the two added with allowElement() (<p> and <span>).

This example shows the effect of using allowElement() to add elements that are already allowed, or that are in the configuration as "to be removed".

<pre id="log"></pre>

#log {
  height: 400px;
  overflow: scroll;
  padding: 0.5rem;
  border: 1px solid black;
}

const logElement = document.querySelector("#log");
function log(text) {
  logElement.textContent = text;
}

JavaScript

The code first creates a new Sanitizer object that initially allows <div> elements (removing attributes other than id) and also replaced <span> elements with any child elements.

It then calls allowElement(), firstly to add a <div> element that removes style attributes. Since the <div> element is already allowed, it is removed from the elements configuration and the <div> element definition is appended.

A <span> element is then added to the allow list, which removes it from the replaceWithChildrenElements configuration list.

if ("Sanitizer" in window) {

// Create sanitizer using SanitizerConfig
const sanitizer = new Sanitizer({
  elements: [{ name: "div", attributes: [{ name: "id" }] }],
  replaceWithChildrenElements: ["span"],
});

// Allow <div> elements.
// Allow id elements but strip their style attributes
sanitizer.allowElement({
  name: "div",
  removeAttributes: ["style"],
});

// Allow <span> elements
sanitizer.allowElement("span");

let sanitizerConfig = sanitizer.get();
log(JSON.stringify(sanitizerConfig, null, 2));

} else {
  log("The HTML Sanitizer API is NOT supported in this browser.");
}

Results

The final configuration is logged, and is shown below. From the log we can see that the original filter for the <div> element has been removed and the new definition appended to the elements list. Adding the <span> element to the elements list has removed it from the replaceWithChildrenElements list.