Champion: Mathias Bynens (Google, @mathiasbynens).
This proposal is at stage 4 of the TC39 process, and is scheduled to be included in ES2021.
(Also see our TL;DR explainer.)
Currently there is no way to replace all instances of a substring in a string without use of a global regexp.
String.prototype.replace only affects the first occurrence when used with a string argument. There is a lot of evidence that developers are trying to do this in JS — see the StackOverflow question with thousands of votes.
Currently the most common way of achieving this is to use a global regexp.
const queryString = 'q=query+string+parameters'; const withSpaces = queryString.replace(/\+/g, ' ');
This approach has the downside of requiring special RegExp characters to be escaped — note the escaped
An alternate solution is to combine
const queryString = 'q=query+string+parameters'; const withSpaces = queryString.split('+').join(' ');
This approach avoids any escaping but comes with the overhead of splitting the string into an array of parts only to glue it back together.
We propose the addition of a new method to the String prototype -
replaceAll. This would give developers a straight-forward way to accomplish this common, basic operation.
const queryString = 'q=query+string+parameters'; const withSpaces = queryString.replaceAll('+', ' ');
It also removes the need to escape special regexp characters (note the unescaped
The proposed signature is the same as the existing
Per the current TC39 consensus,
String.prototype.replaceAll behaves identically to
String.prototype.replace in all cases, except for the following two cases:
searchValueis a string,
String.prototype.replaceonly replaces a single occurrence of the
String.prototype.replaceAllreplaces all occurrences of the
.split(searchValue).join(replaceValue)or a global & properly-escaped regular expression had been used).
searchValueis a non-global regular expression,
String.prototype.replacereplaces a single match, whereas
String.prototype.replaceAllthrows an exception. This is done to avoid the inherent confusion between the lack of a global flag (which implies "do NOT replace all") and the name of the method being called (which strongly suggests "replace all").
String.prototype.replaceAll behaves just like
searchValue is a global regular expression.
Comparison to other languages
- Java has
replace, accepting a
CharSequenceand replacing all occurrences. Java also has
replaceAllwhich accepts a regex as the search term (requiring the user to escape special regex characters), again replacing all occurrences by default.
replacereplaces all occurrences, but accepts an optional param to limit the number of replacements.
- PHP has
str_replacewhich has an optional limit parameter like python.
- Ruby has
gsub, accepting a regexp or string, but also accepts a callback block and a hash of match -> replacement pairs.
What are the main benefits?
A simplified API for this common use-case that does not require RegExp knowledge. A way to global-replace strings without having to escape RegExp syntax characters. Possibly improved optimization potential on the VM side.
What about adding a
limit parameter to
A: This is an awkward interface — because the default limit is 1, the user would have to know how many occurrences already exist, or use something like Infinity.
What happens if
searchValue is the empty string?
String.prototype.replaceAll follows the precedent set by
String.prototype.replace, and returns the input string with the replacement value spliced in between every UCS-2/UTF-16 code unit.
'x'.replace('', '_'); // → '_x' 'xxx'.replace(/(?:)/g, '_'); // → '_x_x_x_' 'xxx'.replaceAll('', '_'); // → '_x_x_x_'