docs.rodeo

MDN Web Docs mirror

SanitizerConfig

{{APIRef("HTML Sanitizer API")}} {{SeeCompatTable}} 

The SanitizerConfig dictionary of the HTML Sanitizer API specifies what elements, attributes and comments are allowed or should be removed when inserting strings of HTML into an {{domxref("Element")}}  or {{domxref("ShadowRoot")}} , or when parsing an HTML string into a {{domxref("Document")}} .

Note that normally {{domxref("Sanitizer")}}  instances are used instead of SanitizerConfig objects, as they are more efficient to share and modify.

Instance properties

Description

A SanitizerConfig specifies what elements, attributes and comments are allowed or should be removed when inserting strings of HTML into an {{domxref("Element")}}  or {{domxref("ShadowRoot")}} , or when parsing an HTML string into a {{domxref("Document")}} .

An instance of this type can be passed to the {{domxref("Sanitizer.Sanitizer", "Sanitizer()")}}  constructor to configure a {{domxref("Sanitizer")}} , and is returned by {{domxref('Sanitizer.get()')}} . It can also be passed as the option.sanitizer parameter when calling the sanitization methods:

Valid configuration

The configuration object structure allows for the declaration of filter options that are contradictory or redundant, such as specifying an element in both allow and remove lists, or listing an attribute in a list multiple times. In order to avoid any ambiguity, methods that take a SanitizerConfig instance require that a valid configuration object be passed, and will throw a {{jsxref("TypeError")}}  if an invalid configuration is used.

In a valid sanitizer configuration:

The empty object {} is a valid configuration.

[!NOTE] The conditions above are from the perspective of a web developer. The validity check defined in the specification is slightly different because it is executed after canonicalization of the configuration, such as adding removeElements when both are missing, and adding default namespaces.

Allow and remove configurations

One of the main implications of the previous section is that a valid configuration can specify either elements or removeElements arrays (but not both) and either the attributes or removeAttributes arrays (but not both).

A configuration that has the elements and/or attributes arrays is referred to as an allow configuration, as it defines the sanitization behavior in terms of the values that are allowed to be present in the output. A remove configuration is one that has either of removeElements and/or removeAttributes, and defines the behavior in terms of the values that will be removed from the output.

Examples

Creating an “allow” configuration

This example shows how you might create an “allow” sanitizer configuration that allows specific elements and attributes, replaces {{htmlelement("b")}}  elements with their children, allows comments to be included in the output, and requires that data-* attributes are explicitly listed in the attributes array to be included. The configuration object is passed to the {{domxref("Sanitizer.Sanitizer", "Sanitizer()")}}  constructor.

const sanitizer = new Sanitizer({
  elements: ["div", "p", "script"],
  attributes: ["id"],
  replaceWithChildrenElements: ["b"],
  comments: true,
  dataAttributes: false,
});

Creating a “remove” configuration

This example shows how you might create a “remove” sanitizer configuration that removes both elements and attributes.

const sanitizer = new Sanitizer({
  removeElements: ["span", "script"],
  removeAttributes: ["lang", "id"],
  comments: false,
});

Allow element and remove attribute configuration

This example shows how you might create a “hybrid” sanitizer configuration that allows some elements and removes certain attributes. You might similarly specify a configuration that removes elements and allows attributes.

const sanitizer = new Sanitizer({
  elements: ["span", "script"],
  removeAttributes: ["lang", "id"],
});

Note that you having both allow and remove arrays for elements, or both allow and remove arrays for attributes is not a valid configuration, and would result in a TypeError.

Invalid configurations

This sections shows a number of invalid configurations. These will throw a TypeError.

Invalid because both elements and removeElements are defined:

const sanitizer1 = new Sanitizer({
  elements: ["span", "script"],
  removeElements: ["div", "b"],
});

Invalid because {{htmlelement("span")}}  is in both elements and replaceWithChildrenElements:

const sanitizer2 = new Sanitizer({
  elements: ["span", "div"],
  replaceWithChildrenElements: ["span"],
});

Invalid because the redundant attribute "data-test" is defined when dataAttributes is true:

const sanitizer3 = new Sanitizer({
  attributes: ["lang", "id", "data-test"],
  dataAttributes: true,
});

Invalid because it has removeAttributes and dataAttributes defined:

const sanitizer4 = new Sanitizer({
  removeAttributes: ["lang", "id"],
  dataAttributes: true,
});

Specifications

{{Specifications}} 

Browser compatibility

{{Compat}} 

In this article

View on MDN