Skip to content
Tutorials Center
My learning

Topics

JavaScript Reference ยท String

String.prototype.replaceAll()

Reference for JavaScript String.prototype.replaceAll(): replace every occurrence of a string or a global regular expression, with replacer functions and examples.

The replaceAll() method returns a new string in which every match of a pattern is replaced. The pattern can be a string, which is matched literally, or a regular expression, which must have the global (g) flag.

Before this method existed, replacing every occurrence of a plain string meant either split("x").join("y") or building a regular expression with escaping. replaceAll() makes the intent obvious and treats a string pattern as plain text.

JavaScript
"a-b-c".replaceAll("-", "+"); // "a+b+c"

Try it

JS Every occurrence

Press Run (or Ctrl + Enter) to see the console output here.

No output.

JS Regular expressions need the g flag

Press Run (or Ctrl + Enter) to see the console output here.

No output.

Syntax

JavaScript
string.replaceAll(pattern, replacement)
Name Description
pattern A string, or a regular expression with the g flag. A string is matched literally.
replacement A string or a function. The same $ patterns as in replace() work in strings: $$, $&, $`, $', $1...$99 and $<name>.

A replacer function receives the matched text, then the capture groups (for a regular expression), then the offset of the match and the whole string, and a groups object when the regular expression has named groups.

Return value: a new string. The original is unchanged.

Exceptions: a TypeError is thrown if the pattern is a regular expression without the g flag.

Usage notes

  • The g flag is mandatory for regular expressions. This is deliberate, so that a missing flag cannot silently replace only the first match.
  • String patterns are literal. "a.b".replaceAll(".", "-") replaces the dot only, not every character.
  • Matches do not overlap and are not rescanned. Replacing "aa" with "a" in "aaaa" gives "aa", not "a", because the inserted text is not searched again.
  • Empty pattern: an empty string matches at every position, including before the first and after the last character, so "abc".replaceAll("", "-") gives "-a-b-c-". Positions are code units, so surrogate pairs are split.
  • Special $ patterns in the replacement string are expanded even for string patterns. To insert user text exactly, return it from a function.
  • Equivalent to replace() with g when the pattern is a regular expression. With a string, replaceAll() is usually clearer and avoids escaping.
  • Case-insensitive plain-text replacement needs a regular expression with the gi flags, with special characters escaped.
  • Performance: each call scans the string once and builds a new one, so chaining many calls on a huge string creates intermediate copies.

Browser support

String.prototype.replaceAll() is newer than replace(). It works in current browsers, but check a compatibility table if you must support older ones.