String.prototype.replace()

Definition

String.prototype.replace() returns a new string with matches of a pattern replaced by a replacement. The original string is never changed — like every string method, replace() produces a copy. It is how you swap text: fix a typo, fill in a template slot, strip unwanted characters, reformat a value.

The single most important thing to know is that when the pattern is a plain string, replace() swaps only the first match. To replace every occurrence you either pass a global regular expression (/x/g) or use the newer replaceAll(). This first-match-only behavior is the number-one surprise for people new to the method.

Syntax

str.replace(pattern, replacement)

// pattern:     a string (first match) or a RegExp (add /g for all matches)
// replacement: a string (with $-patterns) or a function returning the replacement

Parameters

In a string replacement, special patterns let you reuse the matched text: $& is the whole match, $1…$n are regex capture groups, and $$ inserts a literal dollar sign. When replacement is a function, it receives the match (and any capture groups) and returns the text to insert — ideal when the replacement depends on what was matched.

Return value

A new string with the replacement applied. If the pattern matches nothing, the original string is returned unchanged (as a new value). The receiver string itself is never modified.

• A string pattern replaces only the first match.
• A regex without g replaces the first match; with g it replaces all matches.
• The return value must be captured — str.replace(...) on its own line does nothing observable.

Examples

Replace the first match

Replace every match

const s = 'cat, cat, cat';

console.log(s.replace(/cat/g, 'dog')); // 'dog, dog, dog' — global regex
console.log(s.replaceAll('cat', 'dog')); // 'dog, dog, dog' — replaceAll

Reorder with capture groups

const date = '2026-08-02';

// $1, $2, $3 refer to the parenthesised groups
const out = date.replace(/(\d{4})-(\d{2})-(\d{2})/, '$3/$2/$1');
console.log(out); // '02/08/2026'

Compute the replacement with a function

const prices = 'a=5 b=10';

// double every number in the string
const doubled = prices.replace(/\d+/g, (m) => Number(m) * 2);
console.log(doubled); // 'a=10 b=20'

Replace ignoring case

const s = 'JS js Js';
console.log(s.replace(/js/gi, 'JavaScript'));
// 'JavaScript JavaScript JavaScript'

Regex flags compose: g replaces every match and i makes the match case-insensitive, so /js/gi catches JS, js and Js alike. Being able to combine flags like this is the main reason to prefer a regex over a plain string once the match is anything more than an exact, single, case-sensitive substring.

Browser & runtime support

replace() vs replaceAll()

replaceAll() was added in 2021 and does exactly what its name says — it replaces every occurrence of a string pattern without needing a regex. It still accepts a regex, but that regex must carry the g flag or it throws, which neatly prevents the silent "only replaced the first one" bug. On current browsers and Node.js, replaceAll('x', 'y') is the clearest way to replace all literal occurrences.

One more caution when the pattern comes from user input: a string pattern is matched literally, but if you build a RegExp from user text, characters like ., *, ( and ? become regex operators. Escape them first, or prefer replaceAll with a string pattern, so that a search for a.b doesn't quietly also match axb. Treating untrusted input as a literal string is both safer and usually what the user expects.

Availability

replace() has existed since the first edition of JavaScript. The all-matches convenience method replaceAll() arrived in 2021 and is available in every current browser and maintained Node.js release; a global regex (/x/g) with replace() remains the compatible fallback.

Frequently asked questions

Why does replace() only change the first match?

With a string pattern, replace() swaps only the first occurrence by design. Use a global regex (/x/g) or replaceAll('x', 'y') to replace every match.

How do I replace all occurrences of a substring?

Use str.replaceAll('old', 'new'), or str.replace(/old/g, 'new') with a global regex. A plain string passed to replace() only changes the first match.

Does replace() change the original string?

No. Strings are immutable, so replace() returns a new string and leaves the original unchanged. Capture the return value to use the result.

What do $1 and $& mean in the replacement?

In a string replacement, $& inserts the whole match and $1, $2, … insert regex capture groups. Use $$ to insert a literal dollar sign.