replaceAll()
method is supported by Firefox but not by Chrome. It will become available in Chrome 85.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.
The source for this interactive example is stored in a GitHub repository. If you'd like to contribute to the interactive examples project, please clone https://github.com/mdn/interactive-examples and send us a pull request.
Syntax
const newStr = str.replaceAll(regexp|substr, newSubstr|function)
when using a `regexp` you must have to set the global ("g") flag; otherwise, it will throw a TypeError
: "replaceAll must be called with a global RegExp".
Parameters
regexp
(pattern)- A
RegExp
object or literal with the global flag. The matches are replaced withnewSubstr
or the value returned by the specifiedfunction
. A RegExp without the global ("g") flag will throw aTypeError
: "replaceAll must be called with a global RegExp". substr
- A
String
that is to be replaced bynewSubstr
. It is treated as a literal string and is not interpreted as a regular expression. newSubstr
(replacement)- The
String
that replaces the substring specified by the specifiedregexp
orsubstr
parameter. A number of special replacement patterns are supported; see the "Specifying a string as a parameter" section below. function
(replacement)- A function to be invoked to create the new substring to be used to replace the matches to the given
regexp
orsubstr
. The arguments supplied to this function are described in the "Specifying a function as a parameter" section below.
Return value
A new string, with all matches of a pattern replaced by a replacement.
Description
This method does not change the calling String
object. It simply returns a new string.
Specifying a string as a parameter
The replacement string can include the following special replacement patterns:
Pattern | Inserts |
---|---|
$$ |
Inserts a "$" . |
$& |
Inserts the matched substring. |
$` |
Inserts the portion of the string that precedes the matched substring. |
$' |
Inserts the portion of the string that follows the matched substring. |
$n |
Where n is a positive integer less than 100, inserts the n th parenthesized submatch string, provided the first argument was a RegExp object. Note that this is 1 -indexed. |
Specifying a function as a parameter
You can specify a function as the second parameter. In this case, the function will be invoked after the match has been performed. The function's result (return value) will be used as the replacement string. (Note: The above-mentioned special replacement patterns do not apply in this case.)
Note that the function will be invoked multiple times for each full match to be replaced if the regular expression in the first parameter is global.
The arguments to the function are as follows:
Possible name | Supplied value |
---|---|
match |
The matched substring. (Corresponds to $& above.) |
p1, p2, ... |
The nth string found by a parenthesized capture group, provided the first argument to replace() was a RegExp object. (Corresponds to $1 , $2 , etc. above.) For example, if /(\a+)(\b+)/ , was given, p1 is the match for \a+ , and p2 for \b+ . |
offset |
The offset of the matched substring within the whole string being examined. (For example, if the whole string was 'abcd' , and the matched substring was 'bc' , then this argument will be 1 .) |
string |
The whole string being examined. |
(The exact number of arguments depends on whether the first argument is a RegExp
object—and, if so, how many parenthesized submatches it specifies.)
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 (ECMA-262) The definition of 'String.prototype.replaceAll' in that specification. |
Browser compatibility
The compatibility table in this page is generated from structured data. If you'd like to contribute to the data, please check out https://github.com/mdn/browser-compat-data and send us a pull request.
Desktop | Mobile | Server | |||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|
replaceAll | Chrome Full support 85 | Edge No support No | Firefox Full support 77 | IE No support No | Opera No support No | Safari Full support 13.1 | WebView Android Full support 85 | Chrome Android Full support 85 | Firefox Android No support No | Opera Android No support No | Safari iOS Full support 13.4 | Samsung Internet Android No support No | nodejs No support No |
Legend
- Full support
- Full support
- No support
- No support