---
hide_title: false
hide_table_of_contents: false
pagination_next: null
pagination_prev: null
---
# 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.

## Syntax

```js
replaceAll(pattern, replacement)
```

### Parameters

- `pattern`

  - : Can be a string or an object with a [`Symbol.replace`](../../../globals/Symbol/replace.mdx) method — the typical example being a [regular expression](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/RegExp). 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`](../../../globals/TypeError/TypeError.mdx) is thrown.

- `replacement`
  - : Can be a string or a function. The replacement has the same semantics as that of [`String.prototype.replace()`](../../../globals/String/prototype/replace.mdx).

### Return value

A new string, with all matches of a pattern replaced by a replacement.

### Exceptions

- [`TypeError`](../../../globals/TypeError/TypeError.mdx)
  - : Thrown if the `pattern` [is a regex](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/RegExp#special_handling_for_regexes) that does not have the global (`g`) flag set (its [`flags`](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/RegExp/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 [`String.prototype.replace()`](../../../globals/String/prototype/replace.mdx), 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()`](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/RegExp/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`](../../../globals/Symbol/replace.mdx) 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 [`String.prototype.split()`](../../../globals/String/prototype/split.mdx) behavior.

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

For more information about how regex properties (especially the [sticky](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/RegExp/sticky) flag) interact with `replaceAll()`, see [`RegExp.prototype[@@replace]()`](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/RegExp/@@replace).
