JS: String.prototype.replaceAll

By Xah Lee. Date: . Last updated: .

New in JS2021.

str.replaceAll(str1, str2)
Replace all occurrences of string str1 by string str2. Return the new string. If no match, the original string is returned. No regex is used. Original string is not changed.
str.replaceAll(regex, str_or_func)
Use regex to replace all occurrences. regex must have the global flag g.
str_or_func can be a string or function. If string, {$1, $2, etc} refers to captured group.

If function, its return value will be used as the replacement string. The function is called for each match. The function receive variable count of args, in this order:

  • matched substring.
  • capture group 1. (named capture is also a numbered capture)
  • capture group 2, etc.
  • offset position (integer), of the matched substring in the target string.
  • Whole target string.
  • A object of named capture groups. Key is capture name, value is corresponding substring. (or undefined if none).
Original string is not changed.

[see Regex Functions]

[see RegExp Syntax]

When using regex, the following dollar sign sequence have special meaning in the replace string.

$n
nth captured match. (n is a positive integer less than 100)
$<name>
refers to named capture name.
$&
the matched string.
$`
the string before the matched string.
$'
the string after the matched string.
$$
literal dollar sign character.

No Regex Example

console.log("a.b.c".replaceAll(".", "9") === "a9b9c"); // true

Regex Example

Basic example:

 console.log( "xyz x1 x2 x3".replaceAll( /x(\d+)/g, "y$1") );
// xyz y1 y2 y3

With captured group:

// add alt attribute to a HTML image tags

const x1 = `
<img src="cat.jpg">
<img src="dog.jpg">
<img src="mouse.jpg">
`;

const x2 = x1.replaceAll(
  /<img src="([-\w]+)\.jpg">/g,
  '<img src="$1.jpg" alt="$1">',
);

console.log(x2);

/* [
<img src="cat.jpg" alt="cat">
<img src="dog.jpg" alt="dog">
<img src="mouse.jpg" alt="mouse">
] */

With a function as second argument:

// example of RegExp replace, using function as replacement

// add a alt attribute to a HTML image tags, but convert any underscore to space.
// for example
// <img src="my_cat.jpg">
// become
// <img src="my_cat.jpg" alt="my cat">

const ff =
  ((
    whole,
    group1,
  ) => (`<img src="${group1}.jpg" alt="${group1.replace(/_/g, " ")}">`));

const x1 = `
<img src="big_black_cat.jpg">
<img src="little_puppy.jpg">
<img src="red_bird.jpg">
`;

const x2 = x1.replaceAll(/<img src="([-\w]+)\.jpg">/g, ff);

console.log(x2);
/* [
<img src="big_black_cat.jpg" alt="big black cat">
<img src="little_puppy.jpg" alt="little puppy">
<img src="red_bird.jpg" alt="red bird">
] */

Show arguments received by function:

// show arguments received by function

const ff = ((...args) => {
  console.log(args);
  return "3";
});

const txt = `
<img src="big_black_cat.jpg">
<img src="small_cat.jpg">
`;

const regex = /<img src="(?<imgName>[-\w]+)\.jpg">/g;

console.log(txt.replaceAll(regex, ff));

/* [
output
[
  '<img src="big_black_cat.jpg">',
  "big_black_cat",
  1,
  '\n<img src="big_black_cat.jpg">\n<img src="small_cat.jpg">\n',
  { imgName: "big_black_cat" }
]
[
  '<img src="small_cat.jpg">',
  "small_cat",
  31,
  '\n<img src="big_black_cat.jpg">\n<img src="small_cat.jpg">\n',
  { imgName: "small_cat" }
]

3
3

] */
JS in Depth
XAH
Buy Xah JavaScript Tutorial
JS in Depth
XAH

JS Obj Ref

DOM


JS Obj Ref

String

prototype