Skip to main content
Version: 3.28.0

String.prototype.replaceAll()

The replaceAll() method returns a new string with all matches of a pattern replaced by a replacement. The pattern can be a string or a RegExp, and the replacement can be a string or a function to be called for each match. The original string is left unchanged.

Syntax​

replaceAll(pattern, replacement)

Parameters​

  • pattern

    • : Can be a string or an object with a Symbol.replace method — the typical example being a regular expression. Any value that doesn't have the Symbol.replace method will be coerced to a string.

      If pattern is a regex, then it must have the global (g) flag set, or a TypeError is thrown.

  • replacement

Return value​

A new string, with all matches of a pattern replaced by a replacement.

Exceptions​

  • TypeError
    • : Thrown if the pattern is a regex that does not have the global (g) flag set (its flags property does not contain "g").

Description​

This method does not mutate the string value it's called on. It returns a new string.

Unlike String.prototype.replace(), this method would replace all occurrences of a string, not just the first one. This is especially useful if the string is not statically known, as calling the RegExp() constructor without escaping special characters may unintentionally change its semantics.

function unsafeRedactName(text, name) {
  return text.replace(new RegExp(name, "g"), "[REDACTED]");
}
function safeRedactName(text, name) {
  return text.replaceAll(name, "[REDACTED]");
}

const report =
  "A hacker called ha.*er used special characters in their name to breach the system.";

console.log(unsafeRedactName(report, "ha.*er")); // "A [REDACTED]s in their name to breach the system."
console.log(safeRedactName(report, "ha.*er")); // "A hacker called [REDACTED] used special characters in their name to breach the system."

If pattern is an object with a Symbol.replace method (including RegExp objects), that method is called with the target string and replacement as arguments. Its return value becomes the return value of replaceAll(). In this case the behavior of replaceAll() is entirely encoded by the Symbol.replace method, and therefore will have the same result as replace() (apart from the extra input validation that the regex is global).

If the pattern is an empty string, the replacement will be inserted in between every UTF-16 code unit, similar to String.prototype.split() behavior.

"xxx".replaceAll("", "_"); // "_x_x_x_"

For more information about how regex properties (especially the sticky flag) interact with replaceAll(), see RegExp.prototype[@@replace]().