String.prototype.replaceAll()
Baseline Widely available
This feature is well established and works across many devices and browser versions. It’s been available across browsers since August 2020.
The replaceAll()
method of String
values 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.
Try it
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 theSymbol.replace
method will be coerced to a string.If
pattern
is 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 of
String.prototype.replace()
.
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 (itsflags
property does not contain"g"
).
Description
This method does not mutate the string value it's called on. It returns a new string.
Unlike 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 split()
behavior.
"xxx".replaceAll("", "_"); // "_x_x_x_"
For more information about how regex properties (especially the sticky flag) interact with replaceAll()
, see RegExp.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
Specification |
---|
ECMAScript Language Specification # sec-string.prototype.replaceall |
Browser compatibility
BCD tables only load in the browser