ThereplaceAll() method ofString values returns a new string with all matches of apattern replaced by areplacement. Thepattern can be a string or aRegExp, and thereplacement can be a string or a function to be called for each match. The original string is left unchanged.

Try it

const paragraph = "I think Ruth's dog is cuter than your dog!";console.log(paragraph.replaceAll("dog", "monkey"));// Expected output: "I think Ruth's monkey is cuter than your monkey!"// Global flag required when calling replaceAll with regexconst regex = /dog/gi;console.log(paragraph.replaceAll(regex, "ferret"));// Expected output: "I think Ruth's ferret is cuter than your ferret!"

Syntax

replaceAll(pattern, replacement)

Parameters

pattern

Can be a string or an object with aSymbol.replace method — the typical example being aregular expression. Any value that doesn't have theSymbol.replace method will be coerced to a string.

Ifpatternis a regex, then it must have the global (g) flag set, or aTypeError is thrown.

replacement

Can be a string or a function. The replacement has the same semantics as that ofString.prototype.replace().

Return value

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

Exceptions

TypeError

Thrown if thepatternis a regex that does not have the global (g) flag set (itsflags property does not contain"g").

Description

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

Unlikereplace(), this method replaces all occurrences of a string, not just the first one. While it is also possible to usereplace() with a global regex dynamically constructed withRegExp() to replace all instances of a string, this can have unintended consequences if the string contains special characters that have meaning in regular expressions (which might happen if the replacement string comes from user input). While you can mitigate this case usingRegExp.escape() to make the regular expression string into a literal pattern, it is simpler to pass the string toreplaceAll() directly, without converting it to a regex.

function unsafeRedactName(text, name) {  return text.replace(new RegExp(name, "g"), "[REDACTED]");}function semiSafeRedactName(text, name) {  return text.replaceAll(name, "[REDACTED]");}function superSafeRedactName(text, name) {  // only match at word boundaries  return text.replaceAll(    new RegExp(`\\b${RegExp.escape(name)}\\b`, "g"),    "[REDACTED]",  );}let 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(semiSafeRedactName(report, "ha.*er")); // "A hacker called [REDACTED] used special characters in their name to breach the system."report = "A hacker called acke breached the system.";console.log(semiSafeRedactName(report, "acke")); // "A h[REDACTED]r called [REDACTED] breached the system."console.log(superSafeRedactName(report, "acke")); // "A hacker called [REDACTED] breached the system."

Ifpattern is an object with aSymbol.replace method (includingRegExp objects), that method is called with the target string andreplacement as arguments. Its return value becomes the return value ofreplaceAll(). In this case the behavior ofreplaceAll() is entirely encoded by the[Symbol.replace]() method, and therefore will have the same result asreplace() (apart from the extra input validation that the regex is global).

If thepattern is an empty string, the replacement will be inserted in between every UTF-16 code unit, similar tosplit() behavior.

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

For more information about how regex properties (especially thesticky flag) interact withreplaceAll(), seeRegExp.prototype[Symbol.replace]().

Examples

Using replaceAll()

"aabbcc".replaceAll("b", ".");// 'aa..cc'

Non-global regex throws

When using a regular expression search value, it must be global. This won't work:

"aabbcc".replaceAll(/b/, ".");// TypeError: replaceAll must be called with a global RegExp

This will work:

"aabbcc".replaceAll(/b/g, ".");("aa..cc");

Specifications

Browser compatibility

See also

• Polyfill ofString.prototype.replaceAll incore-js
• es-shims polyfill ofString.prototype.replaceAll
• Regular expressions guide
• String.prototype.replace()
• String.prototype.match()
• RegExp.prototype.exec()
• RegExp.prototype.test()