String.prototype.replaceAll()

replaceAll(searchFor, replaceWith)

The replaceAll() method returns a new string with all occurrences of a specified value replaced. Introduced in ES2021, it solves a long-standing pain point: replacing every instance of a substring without needing a global regular expression.

Syntax

string.replaceAll(searchFor, replaceWith)

Parameters

• searchFor — The value to search for. Can be a string or a global regular expression.
• replaceWith — The value to replace matches with. Can be a string or a function.

String vs Regex: The Key Difference

Before replaceAll(), replacing all occurrences required a global regex:

const text = "one one one";

// Using replace() with a string - only replaces first occurrence
text.replace("one", "X");
// "X one one"

// Using replace() with global regex - replaces all
text.replace(/one/g, "X");
// "X X X"

// Using replaceAll() with a string - replaces all directly
text.replaceAll("one", "X");
// "X X X"

This is the core advantage: replaceAll() lets you replace all occurrences using a plain string — no regex syntax required.

Global Regex Requirement

When using a regex with replaceAll(), it must be global (include the g flag). Non-global regexes will throw a TypeError:

const text = "a b a b a b";

// Valid: global regex works
text.replaceAll(/a/g, "X");
// "X b X b X b"

// Invalid: non-global regex throws TypeError
text.replaceAll(/a/, "X");
// TypeError: replaceAll must be called with a global RegExp

This safety check prevents a common bug where developers accidentally use a non-global regex expecting global replacement.

String Immutability

Like all string methods, replaceAll() returns a new string — the original remains unchanged:

const original = "foo bar foo";
const result = original.replaceAll("foo", "baz");

console.log(original); // "foo bar foo" (unchanged)
console.log(result);    // "baz bar baz" (new string)

Examples

Basic string replacement

The simplest use case: replace all instances of a substring:

const message = "hello hello world";
console.log(message.replaceAll("hello", "hi"));
// "hi hi world"

const template = "{{name}} is {{age}} years old";
console.log(template.replaceAll("{{name}}", "Alice"));
// "Alice is {{age}} years old"

Using a global regex for mass replacement

For complex patterns, use a global regex:

const text = "price: $10, $20, $30, $50";

// Remove all dollar amounts
const cleaned = text.replaceAll(/\$\d+/g, "$0");
console.log(cleaned);
// "price: $0, $0, $0, $0"

// Normalize whitespace
const messy = "a   b    c     d";
console.log(messy.replaceAll(/\s+/g, " "));
// "a b c d"

Data sanitization

replaceAll() is excellent for cleaning user-generated content:

function sanitizeInput(input) {
  return input
    .replaceAll("<", "&lt;")
    .replaceAll(">", "&gt;")
    .replaceAll("&", "&amp;")
    .replaceAll('"', "&quot;")
    .replaceAll("'", "&#x27;");
}

const userComment = 'User says: <script>alert("xss")</script>';
console.log(sanitizeInput(userComment));
// "User says: &lt;script&gt;alert(&quot;xss&quot;)&lt;/script&gt;"

// Another sanitization example: normalize line endings
const multiline = "line1\r\nline2\rline3\nline4";
console.log(multiline.replaceAll(/\r\n|\r|\n/g, "\n"));
// "line1\nline2\nline3\nline4"

When to Use replaceAll() vs replace()

Scenario	Method
Replace all with string pattern	replaceAll() (cleanest)
Replace all with complex pattern	replaceAll(/pattern/g)
Replace first occurrence only	replace()
Replace with function callback	replace() or replaceAll()

Key Behaviors

• Returns a new string; original is unchanged
• Replaces all occurrences by default
• String search requires no regex syntax
• Regex must include g flag (throws TypeError otherwise)
• Works with replacement function as second argument

See Also

• string::replace — Replace first occurrence or use regex
• string::split — Split string into array