String.prototype.replace()

replace(pattern, replacement)

The replace() method returns a new string with some or all matches of a pattern replaced. Unlike replaceAll(), this method only replaces the first match by default when using a string pattern.

Syntax

str.replace(pattern, replacement)
str.replace(regexp, replacement)

• pattern: A string or RegExp to search for
• replacement: A string or function to replace the matched text
• Returns: A new string with replacements made

Parameters

Parameter	Type	Description
pattern	string | RegExp	The pattern to search for. If a string, only the first occurrence is replaced.
replacement	string | function	The replacement string or a function that returns the replacement

Return Value

A new string with the specified replacements. The original string remains unchanged.

Examples

Basic String Replacement

const str = "Hello World";
console.log(str.replace("World", "Universe")); // "Hello Universe"
console.log(str.replace("Hello", "Hi"));       // "Hi World"

Note: Only the first occurrence is replaced when using a string pattern:

const str = "foo foo foo";
console.log(str.replace("foo", "bar")); // "bar foo foo"

Using Regular Expressions

const str = "Hello World";

// Replace all matches with global flag
console.log(str.replace(/o/g, "0"));      // "Hell0 W0rld"

// Case-insensitive replacement
console.log(str.replace(/hello/i, "Hi"));  // "Hi World"

Capture Groups

const name = "John Doe";

// $1 and $2 refer to captured groups
console.log(name.replace(/(\w+) (\w+)/, "$2, $1")); // "Doe, John"

// Using named capture groups
console.log(name.replace(/(?<first>\w+) (?<last>\w+)/, "$<last>, $<first>")); // "Doe, John"

Replacement Function

When the replacement is a function, it receives the matched string and can compute a dynamic replacement:

const numbers = "1 2 3 4 5";

// Double each number
const doubled = numbers.replace(/\d+/g, (match) => {
  return String(Number(match) * 2);
});
console.log(doubled); // "2 4 6 8 10"

The function receives these arguments:

• match: The full matched string
• p1, p2, ...: Capture group matches
• offset: Position of the match in the original string
• string: The entire original string

Replacement Special Characters

In replacement strings, these special characters work:

Sequence	Description
$$	Literal dollar sign
$&	The matched substring
$`	The string before the match
$'	The string after the match
$n	The nth capture group
$<name>	Named capture group

const text = "abc123def";

// Insert text before and after match
console.log(text.replace(/\d+/, "[$&]"));       // "abc[123]def"

// Use matched text in replacement
console.log(text.replace(/(\d+)/, "num: $1")); // "abcnum: 123def"

Edge Cases

// No match found - returns original string
console.log("hello".replace("xyz", "abc")); // "hello"

// Empty pattern inserts at start
console.log("hello".replace("", "-"));    // "-hello"

// Undefined replacement searches for "undefined"
console.log("hello".replace("h", undefined)); // "undefinedello"

// Null pattern throws error
try {
  "hello".replace(null, "x");
} catch (e) {
  console.log(e.message); // Null is not a valid argument
}

Performance

For replacing all occurrences, use replaceAll() or a regex with the global flag. Creating a new RegExp each iteration is slower:

// Slower: creates new RegExp each time
const slow = str.replace(/foo/g, "bar");

// Or use replaceAll (ES2021+)
const fast = str.replaceAll("foo", "bar");

See Also

• string::split — Split string into array
• string::slice — Extract portion of string