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.

Try it

Syntax

replaceAll(regexp, newSubstr)
replaceAll(regexp, replacerFunction)

replaceAll(substr, newSubstr)
replaceAll(substr, replacerFunction)

Note: When using a `regexp` you 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 with newSubstr or the value returned by the specified replacerFunction. A RegExp without the global ("g") flag will throw a TypeError: "replaceAll must be called with a global RegExp".
substr: A String that is to be replaced by newSubstr. 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 specified regexp or substr parameter. A number of special replacement patterns are supported; see the "Specifying a string as a parameter" section below.
replacerFunction (replacement): A function to be invoked to create the new substring to be used to replace the matches to the given regexp or substr. 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 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 if the first argument of an replaceAll() invocation is a RegExp object or regular expression literal, the function will be invoked multiple times.

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 `replaceAll()` 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.
`namedGroups`	An object of all named capturing groups. The keys are the names of the capturing groups and each value is the substring matching the named capture group. If the regular expression doesn't contain any capturing groups, `namedGroups` is undefined.

(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 Language Specification # sec-string.prototype.replaceall

Browser compatibility

	Desktop						Mobile						Server
	Chrome	Edge	Firefox	Internet Explorer	Opera	Safari	WebView Android	Chrome Android	Firefox for Android	Opera Android	Safari on IOS	Samsung Internet	Deno	Node.js
`replaceAll`	85	85	77	No	71	13.1	85	85	79	60	13.4	14.0	1.2	15.0.0

Name	JavaScript
Version
Badge
Last Updated	2022-04-28T06:04:39Z