HTML Markup Sanitizer

A lightweight and dependency-free utility for sanitizing HTML markup according to custom rules. Key features include:

• No external dependencies required;
• Simple yet powerful rule configuration.

Installation

npm i html-formatting

Usage

import { sanitize } from 'html-formating'

sanitize(node, rules)

• node: A DOM element whose children will be formatted according to the specified rules (the container itself will not be affected);
• rules: An object containing the formatting rules (Rules).

Configuration

Rules

Type definition: Rules

There are two types of rules: global rules for text nodes, and a set of valid HTML elements along with corresponding rules for them

| Param | Type | Description | | :---------------- | :--------------------: | :----------------------------------------------------------------- | | text | TextRule | Global rules for text nodes | | validElements | Record<string, Rule> | Set of valid HTML elements along with corresponding rules for them |

TextRule

Global rules for text nodes

| Param | Type | Description | | :-------------- | :------------------------: | :----------------------------------------------------------------------------------------------------------- | | noNBSP | boolean | A predefined handler that removes all non-breaking spaces from the text within the container being processed | | processText | (text: string) => string | A method for defining a custom text handler |

An example of processing text by removing all non-breaking spaces and changing case to uppercase

sanitize(node, {
  text: { noNBSP: true, processText: (text) => text.toUpperCase() }
})
// <p>Hello,[NBSP]World!</p> -> <p>HELLO, WORLD!</p>

Valid Elements

validElements is an object (a record) where each key is a set of valid HTML tags separated by comma, and the value is a manipulation configuration (Rule) appropriate for that set. The specified tags can be retained "as is" without any additional processing by simply assigning an empty object {} as their value. From this, it follows that any HTML tags not mentioned in any rules object key will be removed.

For instance, to preserve only headings and paragraphs in the final HTML markup, the following configuration can be specified:

sanitize(node, {
  validElements: { 'h1,h2,h3,h4,h5,h6,p': {} }
})
// <div><h1 class="title">Title</h1><div class="Caption"><p>Caption</p></div><p><span class="typography">Description</span></p><div>
// -> <div><h1 class="title">Title</h1><p>Caption</p><p>Description</p></div>

Rule

Configuration of additional processing of html elements

| Param | Type | Description | | :------------------ | :------------------------------: | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | convertTo | string | Specifies the HTML element into which this group should be converted | | validAttributes | string | A comma-separated list of allowed attributes.All attributes are valid if the parameter is not specified.It is possible to use a mask to allow a group of attributes, for example data-* | | validStyles | string | A comma-separated list of allowed inline styles.All inline styles are valid if the parameter is not specified.It is possible to use a mask to allow a group of styles, for example font-*.This parameter has no effect if validAttributes is specified but does not include the style attribute | | validClasses | string | A comma-separated list of allowed css classes.All css classes are valid if the parameter is not specified.It is possible to use a mask to allow a group of classes, for example indent-*.This parameter has no effect if validAttributes is specified but does not include the class attribute | | noEmpty | boolean | Indicates whether to remove empty elements | | process | (element: HTMLElement) => void | A method for defining a custom element handler | | validChildren | Record<string, Rule> | Overriding rules for nested elements |

Cases

Convert h1 to h2 and remove all line breaks from headings

const headerRules = {
  br: {
    process: (node) => {
      const space = document.createTextNode(' ')
      node.parentNode.replaceChild(space, node)
    }
  }
}

sanitize(node, {
  validElements: {
    h1: { convertTo: 'h2', validChildren: headerRules },
    'h2,h3,h4,h5,h6': { validChildren: headerRules }
  }
})
// <div><h1>Breaking<br>News</h1></div> -> <div><h2>Breaking News</h2></div>

Add target='_blank' to external links

sanitize(node, {
  validElements: {
    a: {
      process: (link) => {
        if (!link.href.startsWith(window.location.origin)) {
          link.target = '_blank'
        }
      }
    }
  }
})
// <div><a href="https://google.com">Search</a></div> -> <div><a href="https://google.com" target="_blank">Search</a></div>

License

MIT.