{"id":14620,"library":"heti-findandreplacedomtext","title":"DOM Find and Replace Utility","description":"This utility, `heti-findandreplacedomtext`, is a fork of the original `padolsey/findAndReplaceDOMText` library. Its core function is to search for regular expression matches within a given DOM node and subsequently replace or wrap each match with a specified node or piece of text. A key differentiator is its robust handling of matches that span across multiple DOM nodes, ensuring that all fragmented portions of a match are correctly processed and modified. The `heti-` fork specifically introduced an `offset` option to address and fix issues related to browser support for regex lookbehind, enhancing cross-browser compatibility. The package's current stable version, 0.5.0, was published over six years ago, indicating that active development has ceased and the package is largely unmaintained. It is primarily used for client-side DOM manipulation tasks without notable external runtime dependencies. For TypeScript users, community-maintained type definitions (`@types/findandreplacedomtext`) are available.","status":"abandoned","version":"0.5.0","language":"javascript","source_language":"en","source_url":"https://github.com/sivan/findAndReplaceDOMText","tags":["javascript"],"install":[{"cmd":"npm install heti-findandreplacedomtext","lang":"bash","label":"npm"},{"cmd":"yarn add heti-findandreplacedomtext","lang":"bash","label":"yarn"},{"cmd":"pnpm add heti-findandreplacedomtext","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"While older packages primarily use CommonJS, modern bundlers typically handle `import` for this library, but it may not be native ESM. For script tags, it exposes a global `findAndReplaceDOMText`.","wrong":"const findAndReplaceDOMText = require('heti-findandreplacedomtext');","symbol":"findAndReplaceDOMText","correct":"import findAndReplaceDOMText from 'heti-findandreplacedomtext';"},{"note":"The library directly exposes the function globally when included as a script tag, which was common practice for client-side utilities. No explicit `export` is needed in this context.","symbol":"findAndReplaceDOMText (global)","correct":"<!-- In HTML: --><script src=\"path/to/findAndReplaceDOMText.js\"></script>\n<script>\n  findAndReplaceDOMText(document.body, { find: /foo/, wrap: 'span' });\n</script>"},{"note":"TypeScript users should install `@types/findandreplacedomtext` for type definitions, as the library itself is written in JavaScript and does not ship with built-in types.","symbol":"findAndReplaceDOMText (TypeScript)","correct":"import findAndReplaceDOMText from 'heti-findandreplacedomtext';\n// Ensure @types/findandreplacedomtext is installed for type support\n// npm install --save-dev @types/findandreplacedomtext"}],"quickstart":{"code":"document.body.innerHTML = `\n  <p id=\"t1\">\n    123 456 Hello\n  </p>\n  <p id=\"t2\">\n    123 456 Hell<span>o Goodbye</span>\n  </p>\n  <div id=\"t3\">\n    This is a test. Another test word.\n  </div>\n`;\n\nimport findAndReplaceDOMText from 'heti-findandreplacedomtext';\n\nconsole.log('Original DOM content:');\nconsole.log(document.body.innerHTML);\n\n// Example 1: Basic wrap\nfindAndReplaceDOMText(document.getElementById('t1'), {\n  find: /Hello/,\n  wrap: 'em'\n});\n\n// Example 2: Wrap across multiple nodes\nfindAndReplaceDOMText(document.getElementById('t2'), {\n  find: /Hello/,\n  wrap: 'strong'\n});\n\n// Example 3: Replace text using a function\nfindAndReplaceDOMText(document.getElementById('t3'), {\n  find: /test/g,\n  replace: function(portion, match) {\n    const span = document.createElement('span');\n    span.style.color = 'blue';\n    span.textContent = portion.text.toUpperCase();\n    return span;\n  }\n});\n\nconsole.log('\\nModified DOM content:');\nconsole.log(document.body.innerHTML);","lang":"typescript","description":"Demonstrates wrapping text with `em` and `strong` tags, including across node boundaries, and replacing text with a custom element and uppercase transformation."},"warnings":[{"fix":"Change `/pattern/` to `/pattern/g` for global search.","message":"When using regular expressions for the `find` option, ensure the global flag (`/g`) is included if you intend to find and replace all occurrences. Without it, only the first match will be processed.","severity":"gotcha","affected_versions":">=0.1.0"},{"fix":"Set `portionMode: 'first'` in the options object if you desire a different behavior for node boundary handling during replacement.","message":"The default `portionMode` is 'retain', which re-uses existing node boundaries. If you need the entire replacement to reside within the first-found match portion's node, set `portionMode: 'first'`. Most use cases benefit from the default 'retain' behavior.","severity":"gotcha","affected_versions":">=0.4.0"},{"fix":"Sanitize any dynamic or user-provided input before using it within the `replace` function to create new DOM nodes or text content.","message":"When using the `replace` option with a function, be cautious about injecting untrusted user-generated content directly into the DOM, as this can lead to Cross-Site Scripting (XSS) vulnerabilities. Always sanitize inputs.","severity":"gotcha","affected_versions":">=0.1.0"},{"fix":"Optimize by providing a `filterElements` function to ignore irrelevant parts of the DOM, or use `preset: 'prose'` to automatically exclude non-textual elements and limit contexts, improving performance on typical prose content.","message":"Operating on very large or frequently changing DOM trees can lead to performance issues due to extensive DOM traversal and manipulation. Use `filterElements` and `forceContext` to narrow the scope if possible.","severity":"gotcha","affected_versions":">=0.1.0"},{"fix":"Install the type definitions: `npm install --save-dev @types/findandreplacedomtext`.","message":"The package does not ship with TypeScript type definitions directly. While it can be used in TypeScript projects, you'll need to install `@types/findandreplacedomtext` for proper type checking and IDE assistance.","severity":"gotcha","affected_versions":">=0.1.0"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"fix":"If using npm/bundlers, ensure `import findAndReplaceDOMText from 'heti-findandreplacedomtext';` is at the top of your file. If using a script tag, verify the `<script>` tag pointing to `findAndReplaceDOMText.js` is correctly placed and loaded before its usage. Also verify the package name in `npm install` and `import` matches `heti-findandreplacedomtext`.","cause":"The `findAndReplaceDOMText` function was not correctly imported or the library script was not loaded into the page. This is common when mixing module types (e.g., trying to `require` a library designed for global script inclusion) or if the `npm install` command did not target the correct package (`heti-findandreplacedomtext`).","error":"TypeError: findAndReplaceDOMText is not a function"},{"fix":"Modify your `find` regular expression to include the global flag, e.g., change `/myword/` to `/myword/g`.","cause":"When using a regular expression for the `find` option, the global flag (`/g`) was omitted, causing `RegExp.prototype.exec` to only find the first match.","error":"Only the first occurrence of my search term is being replaced/wrapped."},{"fix":"Review your `replace` function to ensure it consistently returns valid DOM nodes or strings. Consider adjusting the `portionMode` option (default is 'retain'). If you need to revert changes, save a clone of the original DOM subtree before modification, as the built-in `revert()` method may fail if the DOM is significantly altered elsewhere.","cause":"This can occur if the `replace` function is not carefully constructing new nodes, or if the `portionMode` is not suitable for the desired outcome, leading to incorrect node splitting or merging. It can also happen when the original DOM structure is heavily modified or normalized after the initial replacement, making reversion unpredictable.","error":"The DOM structure appears corrupted or unexpectedly nested after replacement, especially with complex replacements."}],"ecosystem":"npm"}