html-react-parser 6.0.1 → 6.1.0

package/README.md

@@ -43,6 +43,7 @@ parse('<p>Hello, World!</p>'); // React.createElement('p', {}, 'Hello, World!')
   - [library](#library)
   - [htmlparser2](#htmlparser2)
   - [trim](#trim)
+  - [trustedTypePolicy](#trustedtypepolicy)
 - [Migration](#migration)
   - [v5](#v5)
   - [v4](#v4)
@@ -208,7 +209,7 @@ parse('<br>', {
 
 > [!NOTE]
 >
-> The index will restart at 0 when traversing the node's children so don't rely on index being a unique key. See [#1259](https://github.com/remarkablemark/html-react-parser/issues/1259#issuecomment-1889574133).
+> The index will restart at 0 when traversing the node's children so don't rely on index being a unique key (see [#1259](https://github.com/remarkablemark/html-react-parser/issues/1259#issuecomment-1889574133)).
 
 #### replace with TypeScript
 
@@ -244,7 +245,7 @@ If you're having issues, take a look at our [Create React App example](./example
 
 #### replace element and children
 
-Replace the element and its children (see [demo](https://replit.com/@remarkablemark/html-react-parser-replace-example)):
+Replace the element and its children:
 
 ```tsx
 import parse, { domToReact } from 'html-react-parser';
@@ -335,7 +336,7 @@ parse(html, options);
 
 #### replace and remove element
 
-[Exclude](https://replit.com/@remarkablemark/html-react-parser-56) an element from rendering by replacing it with `<React.Fragment>`:
+Exclude an element from rendering by replacing it with `<React.Fragment>`:
 
 ```tsx
 parse('<p><br id="remove"></p>', {
@@ -443,6 +444,21 @@ However, intentional whitespace may be stripped out:
 parse('<p> </p>', { trim: true }); // React.createElement('p')
 ```
 
+### trustedTypePolicy
+
+When running in a browser, you can pass a [Trusted Types](https://developer.mozilla.org/docs/Web/API/Trusted_Types_API) policy so the parser calls `trustedTypePolicy.createHTML` before assigning content to `innerHTML`:
+
+```ts
+parse('<div>Hello</div>', {
+  trustedTypePolicy: window.trustedTypes?.createPolicy('my-policy', {
+    createHTML(input) {
+      // apply sanitization logic here
+      return DOMPurify.sanitize(input);
+    },
+  }),
+});
+```
+
 ## Migration
 
 ### v6
@@ -511,27 +527,27 @@ Since [v1.1.1](https://github.com/remarkablemark/html-react-parser/releases/tag/
 
 ### Is this XSS safe?
 
-No, this library is _**not**_ [XSS (cross-site scripting)](https://wikipedia.org/wiki/Cross-site_scripting) safe. See [#94](https://github.com/remarkablemark/html-react-parser/issues/94).
+No, this library is **not** [XSS (cross-site scripting)](https://wikipedia.org/wiki/Cross-site_scripting) safe (see [#94](https://github.com/remarkablemark/html-react-parser/issues/94)). However, you can mitigate this risk by enforcing a Content Security Policy (CSP) with [Trusted Types](#trustedtypepolicy).
 
 ### Does invalid HTML get sanitized?
 
-No, this library does _**not**_ sanitize HTML. See [#124](https://github.com/remarkablemark/html-react-parser/issues/124), [#125](https://github.com/remarkablemark/html-react-parser/issues/125), and [#141](https://github.com/remarkablemark/html-react-parser/issues/141).
+No, this library does **not** sanitize HTML (see [#124](https://github.com/remarkablemark/html-react-parser/issues/124), [#125](https://github.com/remarkablemark/html-react-parser/issues/125), and [#141](https://github.com/remarkablemark/html-react-parser/issues/141)).
 
 ### Are `<script>` tags parsed?
 
-Although `<script>` tags and their contents are rendered on the server-side, they're not evaluated on the client-side. See [#98](https://github.com/remarkablemark/html-react-parser/issues/98).
+Although `<script>` tags and their contents are rendered on the server-side, they're not evaluated on the client-side (see [#98](https://github.com/remarkablemark/html-react-parser/issues/98)).
 
 ### Attributes aren't getting called
 
-The reason why your HTML attributes aren't getting called is because [inline event handlers](https://developer.mozilla.org/docs/Web/Guide/Events/Event_handlers) (e.g., `onclick`) are parsed as a _string_ rather than a _function_. See [#73](https://github.com/remarkablemark/html-react-parser/issues/73).
+The reason why your HTML attributes aren't getting called is because [inline event handlers](https://developer.mozilla.org/docs/Web/Guide/Events/Event_handlers) (e.g., `onclick`) are parsed as a _string_ rather than a _function_ (see [#73](https://github.com/remarkablemark/html-react-parser/issues/73)).
 
 ### Parser throws an error
 
-If the parser throws an error, check if your arguments are valid. See ["Does invalid HTML get sanitized?"](#does-invalid-html-get-sanitized).
+If the parser throws an error, check if your arguments are valid (see ["Does invalid HTML get sanitized?"](#does-invalid-html-get-sanitized)).
 
 ### Is SSR supported?
 
-Yes, server-side rendering on Node.js is supported by this library. See [demo](https://replit.com/@remarkablemark/html-react-parser-SSR).
+Yes, server-side rendering on Node.js is supported by this library:
 
 ### Elements aren't nested correctly
 
@@ -564,15 +580,15 @@ parse('<CustomElement>', options); // React.createElement('CustomElement')
 > Warning: <CustomElement> is using incorrect casing. Use PascalCase for React components, or lowercase for HTML elements.
 > ```
 
-See [#62](https://github.com/remarkablemark/html-react-parser/issues/62) and [example](https://replit.com/@remarkablemark/html-react-parser-62).
+See [#62](https://github.com/remarkablemark/html-react-parser/issues/62).
 
 ### TS Error: Property 'attribs' does not exist on type 'DOMNode'
 
-The TypeScript error occurs because `DOMNode` needs to be an instance of domhandler's `Element`. See [migration](#migration) or [#199](https://github.com/remarkablemark/html-react-parser/issues/199).
+The TypeScript error occurs because `DOMNode` needs to be an instance of domhandler's `Element` (see [migration](#migration) or [#199](https://github.com/remarkablemark/html-react-parser/issues/199)).
 
 ### Can I enable `trim` for certain elements?
 
-Yes, you can enable or disable [`trim`](#trim) for certain elements using the [`replace`](#replace) option. See [#205](https://github.com/remarkablemark/html-react-parser/issues/205).
+Yes, you can enable or disable [`trim`](#trim) for certain elements using the [`replace`](#replace) option (see [#205](https://github.com/remarkablemark/html-react-parser/issues/205)).
 
 ### Webpack build warnings
 
@@ -607,7 +623,7 @@ node_modules/htmlparser2/lib/index.d.ts:2:23 - error TS1005: ',' expected.
                         ~~~~~~~~~~~~~
 ```
 
-Then upgrade to the latest version of [typescript](https://www.npmjs.com/package/typescript). See [#748](https://github.com/remarkablemark/html-react-parser/issues/748).
+Then upgrade to the latest version of [typescript](https://www.npmjs.com/package/typescript) (see [#748](https://github.com/remarkablemark/html-react-parser/issues/748)).
 
 ## Performance
 

package/dist/html-react-parser.js

@@ -674,13 +674,16 @@
 		var HEAD = 'head';
 		var BODY = 'body';
 		var FIRST_TAG_REGEX = /<([a-zA-Z]+[0-9]?)/; // e.g., <h1>
+		function getHTMLForInnerHTML(html, trustedTypePolicy) {
+		    return trustedTypePolicy ? trustedTypePolicy.createHTML(html) : html;
+		}
 		// falls back to `parseFromString` if `createHTMLDocument` cannot be used
 		/* eslint-disable @typescript-eslint/no-unused-vars */
 		/* v8 ignore start */
-		var parseFromDocument = function (html, tagName) {
+		var parseFromDocument = function (html, tagName, trustedTypePolicy) {
 		    throw new Error('This browser does not support `document.implementation.createHTMLDocument`');
 		};
-		var parseFromString = function (html, tagName) {
+		var parseFromString = function (html, tagName, trustedTypePolicy) {
 		    throw new Error('This browser does not support `DOMParser.prototype.parseFromString`');
 		};
 		var DOMParser = typeof window === 'object' && window.DOMParser;
@@ -699,7 +702,7 @@
 		     * @param tagName - The element to render the HTML (with 'body' as fallback).
 		     * @returns - Document.
 		     */
-		    parseFromString = function (html, tagName) {
+		    parseFromString = function (html, tagName, trustedTypePolicy) {
 		        if (tagName) {
 		            html = "<".concat(tagName, ">").concat(html, "</").concat(tagName, ">");
 		        }
@@ -722,15 +725,15 @@
 		     * @param tagName - The element to render the HTML (with 'body' as fallback).
 		     * @returns - Document
 		     */
-		    parseFromDocument = function (html, tagName) {
+		    parseFromDocument = function (html, tagName, trustedTypePolicy) {
 		        if (tagName) {
 		            var element = htmlDocument_1.documentElement.querySelector(tagName);
 		            if (element) {
-		                element.innerHTML = html;
+		                element.innerHTML = getHTMLForInnerHTML(html, trustedTypePolicy);
 		            }
 		            return htmlDocument_1;
 		        }
-		        htmlDocument_1.documentElement.innerHTML = html;
+		        htmlDocument_1.documentElement.innerHTML = getHTMLForInnerHTML(html, trustedTypePolicy);
 		        return htmlDocument_1;
 		    };
 		}
@@ -749,8 +752,8 @@
 		     * @param html - HTML string.
 		     * @returns - Nodes.
 		     */
-		    parseFromTemplate = function (html) {
-		        template.innerHTML = html;
+		    parseFromTemplate = function (html, trustedTypePolicy) {
+		        template.innerHTML = getHTMLForInnerHTML(html, trustedTypePolicy);
 		        return template.content.childNodes;
 		    };
 		}
@@ -760,9 +763,10 @@
 		 * Parses HTML string to DOM nodes.
 		 *
 		 * @param html - HTML markup.
+		 * @param trustedTypePolicy - Trusted Types policy.
 		 * @returns - DOM nodes.
 		 */
-		function domparser(html) {
+		function domparser(html, trustedTypePolicy) {
 		    var _a, _b, _c, _d, _e, _f;
 		    // Escape special characters before parsing
 		    html = escapeSpecialCharacters(html);
@@ -785,7 +789,7 @@
 		        }
 		        case HEAD:
 		        case BODY: {
-		            var elements = parseFromDocument(html).querySelectorAll(firstTagName);
+		            var elements = parseFromDocument(html, undefined, trustedTypePolicy).querySelectorAll(firstTagName);
 		            // if there's a sibling element, then return both elements
 		            /* v8 ignore next */
 		            if (hasOpenTag(html, BODY) && hasOpenTag(html, HEAD)) {
@@ -798,9 +802,9 @@
 		        default: {
 		            // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition
 		            if (parseFromTemplate) {
-		                return parseFromTemplate(html);
+		                return parseFromTemplate(html, trustedTypePolicy);
 		            }
-		            var element = parseFromDocument(html, BODY).querySelector(BODY);
+		            var element = parseFromDocument(html, BODY, trustedTypePolicy).querySelector(BODY);
 		            return (_f = element === null || element === void 0 ? void 0 : element.childNodes) !== null && _f !== void 0 ? _f : createNodeList();
 		        }
 		        /* v8 ignore stop */
@@ -812,9 +816,10 @@
 		 * Parses HTML string to DOM nodes in browser.
 		 *
 		 * @param html - HTML markup.
+		 * @param options - Parser options.
 		 * @returns - DOM elements.
 		 */
-		function HTMLDOMParser(html) {
+		function HTMLDOMParser(html, options) {
 		    if (typeof html !== 'string') {
 		        throw new TypeError('First argument must be a string');
 		    }
@@ -824,7 +829,7 @@
 		    // match directive
 		    var match = DIRECTIVE_REGEX.exec(html);
 		    var directive = match ? match[1] : undefined;
-		    return formatDOM(domparser(html), null, directive);
+		    return formatDOM(domparser(html, options === null || options === void 0 ? void 0 : options.trustedTypePolicy), null, directive);
 		}
 
 		htmlToDom.default = HTMLDOMParser;
@@ -2285,14 +2290,14 @@
 	function requireUtilities () {
 		if (hasRequiredUtilities) return utilities$1;
 		hasRequiredUtilities = 1;
-		(function (exports$1) {
+		(function (exports) {
 			var __importDefault = (utilities$1 && utilities$1.__importDefault) || function (mod) {
 			    return (mod && mod.__esModule) ? mod : { "default": mod };
 			};
-			Object.defineProperty(exports$1, "__esModule", { value: true });
-			exports$1.returnFirstArg = exports$1.canTextBeChildOfNode = exports$1.ELEMENTS_WITH_NO_TEXT_CHILDREN = exports$1.PRESERVE_CUSTOM_ATTRIBUTES = void 0;
-			exports$1.isCustomComponent = isCustomComponent;
-			exports$1.setStyleProp = setStyleProp;
+			Object.defineProperty(exports, "__esModule", { value: true });
+			exports.returnFirstArg = exports.canTextBeChildOfNode = exports.ELEMENTS_WITH_NO_TEXT_CHILDREN = exports.PRESERVE_CUSTOM_ATTRIBUTES = void 0;
+			exports.isCustomComponent = isCustomComponent;
+			exports.setStyleProp = setStyleProp;
 			const react_1 = require$$0;
 			const style_to_js_1 = __importDefault(requireCjs());
 			const RESERVED_SVG_MATHML_ELEMENTS = new Set([
@@ -2355,11 +2360,11 @@
 			/**
 			 * @see https://reactjs.org/blog/2017/09/08/dom-attributes-in-react-16.html
 			 */
-			exports$1.PRESERVE_CUSTOM_ATTRIBUTES = Number(react_1.version.split('.')[0]) >= 16;
+			exports.PRESERVE_CUSTOM_ATTRIBUTES = Number(react_1.version.split('.')[0]) >= 16;
 			/**
 			 * @see https://github.com/facebook/react/blob/cae635054e17a6f107a39d328649137b83f25972/packages/react-dom/src/client/validateDOMNesting.js#L213
 			 */
-			exports$1.ELEMENTS_WITH_NO_TEXT_CHILDREN = new Set([
+			exports.ELEMENTS_WITH_NO_TEXT_CHILDREN = new Set([
 			    'tr',
 			    'tbody',
 			    'thead',
@@ -2376,8 +2381,8 @@
 			 * @param node - Element node.
 			 * @returns - Whether the node can contain text nodes.
 			 */
-			const canTextBeChildOfNode = (node) => !exports$1.ELEMENTS_WITH_NO_TEXT_CHILDREN.has(node.name);
-			exports$1.canTextBeChildOfNode = canTextBeChildOfNode;
+			const canTextBeChildOfNode = (node) => !exports.ELEMENTS_WITH_NO_TEXT_CHILDREN.has(node.name);
+			exports.canTextBeChildOfNode = canTextBeChildOfNode;
 			/**
 			 * Returns the first argument as is.
 			 *
@@ -2385,7 +2390,7 @@
 			 * @returns - The input argument `arg`.
 			 */
 			const returnFirstArg = (arg) => arg;
-			exports$1.returnFirstArg = returnFirstArg;
+			exports.returnFirstArg = returnFirstArg;
 			
 		} (utilities$1));
 		return utilities$1;
@@ -3207,24 +3212,24 @@
 	function requireLib () {
 		if (hasRequiredLib) return lib$1;
 		hasRequiredLib = 1;
-		(function (exports$1) {
+		(function (exports) {
 			var __importDefault = (lib$1 && lib$1.__importDefault) || function (mod) {
 			    return (mod && mod.__esModule) ? mod : { "default": mod };
 			};
-			Object.defineProperty(exports$1, "__esModule", { value: true });
-			exports$1.htmlToDOM = exports$1.domToReact = exports$1.attributesToProps = exports$1.Text = exports$1.ProcessingInstruction = exports$1.Element = exports$1.Comment = void 0;
-			exports$1.default = HTMLReactParser;
+			Object.defineProperty(exports, "__esModule", { value: true });
+			exports.htmlToDOM = exports.domToReact = exports.attributesToProps = exports.Text = exports.ProcessingInstruction = exports.Element = exports.Comment = void 0;
+			exports.default = HTMLReactParser;
 			const html_dom_parser_1 = __importDefault(requireHtmlToDom());
-			exports$1.htmlToDOM = html_dom_parser_1.default;
+			exports.htmlToDOM = html_dom_parser_1.default;
 			const attributes_to_props_1 = __importDefault(requireAttributesToProps());
-			exports$1.attributesToProps = attributes_to_props_1.default;
+			exports.attributesToProps = attributes_to_props_1.default;
 			const dom_to_react_1 = __importDefault(requireDomToReact());
-			exports$1.domToReact = dom_to_react_1.default;
+			exports.domToReact = dom_to_react_1.default;
 			var domhandler_1 = require$$3;
-			Object.defineProperty(exports$1, "Comment", { enumerable: true, get: function () { return domhandler_1.Comment; } });
-			Object.defineProperty(exports$1, "Element", { enumerable: true, get: function () { return domhandler_1.Element; } });
-			Object.defineProperty(exports$1, "ProcessingInstruction", { enumerable: true, get: function () { return domhandler_1.ProcessingInstruction; } });
-			Object.defineProperty(exports$1, "Text", { enumerable: true, get: function () { return domhandler_1.Text; } });
+			Object.defineProperty(exports, "Comment", { enumerable: true, get: function () { return domhandler_1.Comment; } });
+			Object.defineProperty(exports, "Element", { enumerable: true, get: function () { return domhandler_1.Element; } });
+			Object.defineProperty(exports, "ProcessingInstruction", { enumerable: true, get: function () { return domhandler_1.ProcessingInstruction; } });
+			Object.defineProperty(exports, "Text", { enumerable: true, get: function () { return domhandler_1.Text; } });
 			const domParserOptions = { lowerCaseAttributeNames: false };
 			/**
 			 * Converts HTML string to React elements.
@@ -3241,7 +3246,8 @@
 			    if (!html) {
 			        return [];
 			    }
-			    return (0, dom_to_react_1.default)((0, html_dom_parser_1.default)(html, (_a = options === null || options === void 0 ? void 0 : options.htmlparser2) !== null && _a !== void 0 ? _a : domParserOptions), options);
+			    const htmlToDOMOptions = Object.assign(Object.assign({}, ((_a = options === null || options === void 0 ? void 0 : options.htmlparser2) !== null && _a !== void 0 ? _a : domParserOptions)), { trustedTypePolicy: options === null || options === void 0 ? void 0 : options.trustedTypePolicy });
+			    return (0, dom_to_react_1.default)((0, html_dom_parser_1.default)(html, htmlToDOMOptions), options);
 			}
 			
 		} (lib$1));