JavaScript String replaceAll() Method

What You’ll Learn

String.prototype.replaceAll() returns a new string with every match of a pattern replaced (same API as MDN String.prototype.replaceAll()). Learn how it differs from replace(), why regexes must use the g flag, empty-string behavior, five examples, and try-it labs.

Introduction

Want every copy of a word swapped — not just the first? replaceAll() is the clear tool for that. Pass a plain string and every occurrence is replaced. Pass a regex and it must include the g flag, or JavaScript throws TypeError.

Compared with replace(/pat/g, …), replaceAll("pat", …) is safer for literal text from users because characters like . and * are not treated as regex metacharacters.

This page is part of JavaScript String Methods. Related topics include replace() and RegExp g flag.

Understanding the replaceAll() Method

str.replaceAll(pattern, replacement) searches for every match of pattern and returns a new string with those matches rewritten.

• A string pattern replaces all occurrences.
• A RegExp pattern must have the g flag.
• Without g, replaceAll throws TypeError.
• replacement may be a string or a function (same rules as replace).
• The original string is never modified.

📝 Syntax

General form of String.prototype.replaceAll:

str.replaceAll(pattern, replacement)

Parameters

• pattern — a string, or a RegExp that includes the g flag. Non-regex values are coerced to strings.
• replacement — a string (may include $&, $1, …) or a function called for each match — same semantics as replace().

Return value

A string with all matches replaced:

Common patterns

"cat cat".replaceAll("cat", "dog");  // "dog dog"
"aabbcc".replaceAll("b", ".");       // "aa..cc"
"aabbcc".replaceAll(/b/g, ".");      // "aa..cc"

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

Examples Gallery

Examples follow MDN String.replaceAll() patterns. Use View Output or Try It Yourself for each case.

const paragraph = "This dog's name is just Dog! Yes, that is the name.";

paragraph.replaceAll("name", "nickname");
// "This dog's nickname is just Dog! Yes, that is the nickname."

paragraph.replaceAll(/\bis\b/g, "was");
// "This dog's name was just Dog! Yes, that was the name."

This dog's nickname is just Dog! Yes, that is the nickname.
This dog's name was just Dog! Yes, that was the name.

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

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

"I love cats and cats!".replaceAll("cats", "dogs");
// "I love dogs and dogs!"

aa..cc
aa..cc
I love dogs and dogs!

try {
  "aabbcc".replaceAll(/b/, ".");
} catch (e) {
  e.name;  // "TypeError"
}

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

TypeError
aa..cc

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

"hi".replaceAll("", "-");
// "-h-i-"

// Contrast with replace (empty pattern prepends once):
"xxx".replace("", "_");
// "_xxx"

_x_x_x_
-h-i-
_xxx

function unsafeRedact(text, name) {
  return text.replace(new RegExp(name, "g"), "[REDACTED]");
}

function safeRedact(text, name) {
  return text.replaceAll(name, "[REDACTED]");
}

const report =
  "A hacker called ha.*er used special characters in their name.";

unsafeRedact(report, "ha.*er");
// "A [REDACTED]s in their name."  (.* ate too much!)

safeRedact(report, "ha.*er");
// "A hacker called [REDACTED] used special characters in their name."

A [REDACTED]s in their name.
A hacker called [REDACTED] used special characters in their name.

🚀 Common Use Cases

• Bulk find-and-replace — swap every copy of a word or token.
• Cleaning user text — remove or mask repeated substrings safely.
• Template cleanup — replace placeholders that appear many times.
• Global regex transforms — with an explicit g flag.
• Not for first-only edits — use replace() when one swap is enough.
• Not for reading matches — use match() / matchAll() to inspect hits.

📝 Notes

• replaceAll with a string pattern replaces every occurrence.
• A regex argument must include the g flag or a TypeError is thrown.
• Empty string pattern inserts between every UTF-16 code unit.
• Prefer string replaceAll for literal text that might contain regex characters.
• Replacement strings support the same $ patterns as replace().
• Always capture the return value — the original string does not update in place.

💡 Best Practices