How to replace all occurrences of a string in JavaScript

1String.prototype.replaceAll()Recommended

replaceAll(search, replacement) finds every occurrence of search and returns a new string with each one swapped. When search is a plain string it is matched literally, so there is nothing to escape. Compare it with replace(), which given a string pattern stops after the first match.

const text = "red apple, red cherry, red plum";

// replace() with a string pattern swaps only the FIRST match
console.log(text.replace("red", "green"));

// replaceAll() swaps every match
console.log(text.replaceAll("red", "green"));

// The pre-2021 idiom: split on the needle, join with the replacement
console.log(text.split("red").join("green"));

// Strings are immutable: the original is untouched
console.log(text);

Output: green apple, red cherry, red plum from replace(), then green apple, green cherry, green plum twice, then the original red apple, red cherry, red plum, unchanged. JavaScript strings are immutable, so always use the return value: text = text.replaceAll(…). You will still see split().join() in older code; it gives the same result and was the usual workaround before replaceAll() arrived in ES2021 (Node 15). There is no reason to write it today.

2A regex with the g flag

A regular expression replaces every match only when it carries the g (global) flag. Without it, replace() stops after the first match, just as it does with a string. Reach for a regex when the thing you are replacing is a shape rather than fixed text, or when case shouldn't matter: add i for that.

const text = "Cat, cat and CAT";

// Without the g flag, a regex also replaces only the first match
console.log(text.replace(/cat/i, "dog"));

// g = global (every match), i = ignore case
console.log(text.replace(/cat/gi, "dog"));

// A regex can match a shape, not just fixed text
console.log("a  b\t\tc   d".replace(/\s+/g, " "));

// replaceAll() refuses a regex that lacks the g flag
try {
  text.replaceAll(/cat/i, "dog");
} catch (err) {
  console.log(`${err.name}: ${err.message}`);
}

Output: dog, cat and CAT (first match only), dog, dog and dog, and a b c d, where /\s+/g collapsed each run of spaces and tabs. The last line is the error people search for: TypeError: String.prototype.replaceAll called with a non-global RegExp argument. replaceAll() accepts a regex, but only a global one, so a missing g fails loudly instead of silently replacing one match. With a g regex, replace() and replaceAll() behave identically.

3Using a variable in a regex: RegExp.escape()

You can't put a variable inside /…/, so the second classic question is how to build a regex at runtime. The answer is new RegExp(string, flags). The catch: the string is read as regex syntax, so a search term containing ., *, +, ?, ( or [ matches something other than you meant. Pass it through RegExp.escape() first. It is new in ES2025 and available in Node 24+ and current Chrome, Firefox and Safari.

const text = "v1.2 and v152 and v1.2.3";
const term = "1.2";

// new RegExp() builds a pattern from a string at runtime...
const naive = new RegExp(term, "g");
console.log(text.replace(naive, "X"));

// ...but "." is a regex metacharacter, so escape the variable first
const safe = new RegExp(RegExp.escape(term), "g");
console.log(safe.source);
console.log(text.replace(safe, "X"));

// Before RegExp.escape existed: the classic escape function
const escapeRegExp = (s) => s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
console.log(escapeRegExp(term));
console.log(text.replace(new RegExp(escapeRegExp(term), "g"), "X"));

// A variable plus flags: every match, any case
const word = "js";
console.log("JS, js and Js".replace(new RegExp(RegExp.escape(word), "gi"), "JavaScript"));

The unescaped pattern prints vX and vX and vX.3: its . matched the 5 in v152, which was never supposed to change. Escaped, the result is the intended vX and v152 and vX.3. safe.source prints \x31\.2, which looks odd but is deliberate: RegExp.escape() also escapes a leading digit or letter, so the output can't merge with a preceding \1 backreference when you glue it into a larger pattern. On older runtimes, the hand-written escapeRegExp (from MDN) gives 1\.2 and the same result. The last line prints JavaScript, JavaScript and JavaScript, which is the reason to build a regex at all. If you only need a literal, case-sensitive replace, skip the regex and call replaceAll(term, …) with the string.

4The $& and $1 replacement-pattern gotcha

The replacement string is not literal either. Both replace() and replaceAll() scan it for special patterns: $& (the whole match), $1–$99 (capture groups), $<name> (a named group), $` and $' (the text before and after the match), and $$ (one literal $). That's handy when you mean it and a data corruption bug when the replacement is user input or a price.

const tpl = "Total: {amount}";

// Used on purpose, the $ patterns are handy
console.log("2026-09-24".replace(/(\d+)-(\d+)-(\d+)/, "$3/$2/$1"));
console.log("ship it".replaceAll("it", "[$&]"));

// Used by accident, they corrupt your data: "$1" means capture group 1
const price = "$10.00";
console.log(tpl.replace(/\{(\w+)\}/, price));

// And "$$" collapses to a single "$"
console.log(tpl.replace("{amount}", "$$20"));

// Fix: pass a function; whatever it returns is inserted literally
console.log(tpl.replace(/\{(\w+)\}/, () => price));
console.log(tpl.replace("{amount}", () => "$$20"));

On purpose, $3/$2/$1 reorders the date to 24/09/2026 and [$&] wraps the match: ship [it]. By accident, the price $10.00 becomes Total: amount0.00, because $1 was read as "group 1" (the word amount) followed by 0.00, and $$20 comes out as Total: $20. The fix is a replacer function: its return value is never scanned for patterns, so the last two lines print Total: $10.00 and Total: $$20 exactly. Use a function whenever the replacement comes from a variable you don't control.

5Which should you use?

6Common variation: several replacements in one pass

Chaining replaceAll() calls works until one replacement produces text that a later call also matches. To swap several strings safely, build one regex that alternates the escaped keys, and let a replacer function look each match up. The same function form also receives the capture groups, so it can transform matches instead of just substituting them.

// Chained replaceAll() calls re-process each other's output
const s = "cat chases dog";
console.log(s.replaceAll("cat", "dog").replaceAll("dog", "cat"));

// One pass instead: an alternation of escaped keys, then a lookup
const swap = { cat: "dog", dog: "cat" };
const re = new RegExp(Object.keys(swap).map((k) => RegExp.escape(k)).join("|"), "g");
console.log(s.replace(re, (match) => swap[match]));

// The function also receives capture groups, so it can transform
const camel = "user_first_name".replace(/_([a-z])/g, (_, letter) => letter.toUpperCase());
console.log(camel);

// Keys that are regex syntax are safe once escaped
const ops = { "+": " plus ", "*": " times " };
const opsRe = new RegExp(Object.keys(ops).map((k) => RegExp.escape(k)).join("|"), "g");
console.log("2+3*4".replace(opsRe, (op) => ops[op]));

The chain prints cat chases cat: the first call turned cat into dog, and the second turned both dogs back into cats. The single pass prints dog chases cat, because every match is replaced exactly once. The replacer's second argument is the first capture group, which gives userFirstName, and the escaped + and * keys produce 2 plus 3 times 4 instead of a SyntaxError. If one key is a prefix of another (a and ab), sort the keys longest first before joining, because the alternation takes the first branch that matches.