replace-dom-string

Replace one or more matching strings/regexes within a DOM tree.

Installation

Node.js >= 10 is required. To install, type this at the command line:

npm install replace-dom-string

Importing

ES Module:

import replaceDOMString from 'replace-dom-string';

CommonJS Module:

const replaceDOMString = require('replace-dom-string');

Usage

Single needle/replacement with default options:

const target = document.querySelector('elm');
// <elm attr="needle">needle</elm>

replaceDOMString('needle', 'replacement', target);
// <elm attr="replacement">replacement</elm>

Single needle/replacement with custom options:

const target = document.querySelector('elm');
// <elm attr="needle">needle</elm>

replaceDOMString('needle', 'replacement', target, {characterData: false});
// <elm attr="replacement">needle</elm>

Multiple needles/replacements (including RegExp) and custom options:

const target = document.querySelector('elm');
/*
<elm attr="foo bar001">
  foo bar001
  <nested attr="foo bar001">foo bar001</nested>
</elm>
*/

replaceDOMString(
  ['foo', /bar(\d+)/g],
  ['baz', 'baz$1'],
  target,
  {attributes: false}
);
/*
<elm attr="foo bar001">
  baz baz001
  <nested attr="foo bar001">baz baz001</nested>
</elm>
*/

Options

At a minimum, one of attributes and/or characterData must be true; otherwise, a TypeError exception will be thrown. Inspired by MutationObserver.

acceptAttribute

Type: Function
Default value: (attribute) => true
A custom filter that is performed for each attribute after the default filtering has deemed such worthy of changes. It must return a boolean.

acceptNode

Type: Function
Default value: (node) => NodeFilter.FILTER_ACCEPT
A custom filter that is performed for each ELEMENT_NODE and TEXT_NODE after the default filtering has deemed such worthy of changes. It must return a NodeFilter.FILTER_* constant.

attributes

Type: Boolean
Default value: true
When true, attribute values will be included in substitution.

characterData

Type: Boolean
Default value: true
When true, Text nodes within the child list of target will be included in substitution.

subtree

Type: Boolean
Default value: true
When true, substitution will be extended to the entire subtree of nodes rooted at target.

Compatibility

Depending on your target browsers, you may need polyfills/shims for the following:

• Array.from
• Array::includes