String.prototype.replaceAll()
=============================

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
------


```js
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 the `Symbol.replace` method will be coerced to a string.

If `pattern` is a regex, then it must have the global (`g`) flag set, or a `TypeError` 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 (its `flags` 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.


```js
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 `@@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.


```js
"xxx".replaceAll("", "\_"); // "\_x\_x\_x\_"
```


For more information about how regex properties (especially the sticky flag) interact with `replaceAll()`, see `RegExp.prototype[@@replace]()`.

Examples
--------

### Using replaceAll()


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

### Non-global regex throws

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


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


This will work:


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

Specifications
--------------

| Specification |
| --- |
| ECMAScript Language Specification # sec-string.prototype.replaceall |

Browser compatibility
---------------------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

See also
--------

* Polyfill of `String.prototype.replaceAll` in `core-js`
* `String.prototype.replace()`
* `String.prototype.match()`
* `RegExp.prototype.exec()`
* `RegExp.prototype.test()`