TheSanitizerConfig dictionary of theHTML Sanitizer API specifies what elements, attributes and comments are allowed or should be removed when inserting strings of HTML into anElement orShadowRoot, or when parsing an HTML string into aDocument.

Note that normallySanitizer instances are used instead ofSanitizerConfig objects, as they are more efficient to share and modify.

Instance properties

elements

An array indicating the elements to allow when sanitizing HTML, optionally also specifying their allowed or removed attributes.

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

name

A string containing the name of the element.

namespaceOptional

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

attributesOptional

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 an object with the following properties:

name

A string containing the name of the attribute.

namespaceOptional

A string containing the namespace of the attribute, which defaults tonull.

removeAttributesOptional

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 an object with the following properties:

name

A string containing the name of the attribute.

namespaceOptional

A string containing the namespace of the attribute, which defaults tonull.

removeElements

An array indicating the elements to remove when sanitizing HTML.

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

name

A string containing the name of the element.

namespaceOptional

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

replaceWithChildrenElements

An array indicating the elements to replace with their content when sanitizing HTML.This is primarily used to strip styles from text (for example, you could use this to change<b>some text</b> tosome text).

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

name

A string containing the name of the element.

namespaceOptional

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

attributes

An array indicating the attributes to allow when sanitizing HTML.

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

name

A string containing the name of the attribute.

namespaceOptional

A string containing the namespace of the attribute, which defaults tonull.

removeAttributes

An array indicating the attributes to remove from elements when sanitizing HTML.

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

name

A string containing the name of the attribute.

namespaceOptional

A string containing the namespace of the attribute, which defaults tonull.

comments

true if comments are allowed, andfalse if they are to be removed.

dataAttributes

true if alldata-* attributes will be allowed (in which casedata-* attributes must not be listed in theattributes array).Iffalse, anydata-* attributes to be allowed must be listed in theattributes array.

Description

ASanitizerConfig specifies what elements, attributes and comments are allowed or should be removed when inserting strings of HTML into anElement orShadowRoot, or when parsing an HTML string into aDocument.

An instance of this type can be passed to theSanitizer() constructor to configure aSanitizer, and is returned bySanitizer.get().It can also be passed as theoption.sanitizer parameter when calling thesanitization methods:

• setHTML() orsetHTMLUnsafe() onElement.
• setHTML() orsetHTMLUnsafe() onShadowRoot.
• Document.parseHTML() orDocument.parseHTMLUnsafe() static 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 aSanitizerConfig instance require that avalid configuration object be passed, and will throw aTypeError if an invalid configuration is used.

In a valid sanitizer configuration:

• Either theelements orremoveElements array may be defined, but not both.

  Note:It is impossible to define per-element attributes if theremoveElements array is defined, because these are added to elements in theelements array.

• Either the globalattributes orremoveAttributes array may be defined, but not both

• ThereplaceWithChildrenElements array, if defined, may not have any elements in common withelements orremoveElements

• No array may contain duplicate elements or attributes

• If the globalattributes array is defined:

  • An element may define any or none ofattributes andremoveAttributes
  • An element'sattributes must not share any values in common with the globalattributes array
  • An element'sremoveAttributes array may only contain values that are also present in the globalattributes array.
  • IfdataAttributes istrue the global and element attribute arrays must not containdata-* attributes (since these will automatically be allowed).

• If the globalremoveAttributes array is defined:

  • An element may specify eitherattributes orremoveAttributes, but not both
  • An element'sattributes orremoveAttributes array, depending on which (if either) is defined, must not share any values in common with the globalremoveAttributes array.
  • ThedataAttributes boolean must not be defined.

The empty object{} is a valid configuration.

Allow and remove configurations

One of the main implications of the previous section is that a valid configuration can specify eitherelements orremoveElements arrays (but not both) and either theattributes orremoveAttributes arrays (but not both).

A configuration that has theelements and/orattributes arrays is referred to as anallow configuration, as it defines the sanitization behavior in terms of the values that are allowed to be present in the output.Aremove configuration is one that has either ofremoveElements and/orremoveAttributes, 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<b> elements with their children, allows comments to be included in the output, and requires thatdata-* attributes are explicitly listed in theattributes array to be included.The configuration object is passed to theSanitizer() 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 avalid configuration, and would result in aTypeError.

Invalid configurations

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

Invalid because bothelements andremoveElements are defined:

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

Invalid because<span> is in bothelements andreplaceWithChildrenElements:

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

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

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

Invalid because it hasremoveAttributes anddataAttributes defined:

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

Specifications

Browser compatibility

api.Sanitizer.get

api.Sanitizer.Sanitizer