JavaScriptStringsBeginner

String.replace()

Replaces the first match of a string/regex and returns a new string.

Review the syntaxStudy the examplesOpen the coding app
string.replace(searchValue, replaceValue)
Open Coding Reference

This static page keeps the syntax and examples indexed for search, while the coding app handles interactive exploration and saved references.

What it does

Overview

Replaces the first match of a string/regex and returns a new string.

The replace() method returns a new string with some or all matches of a pattern replaced by a replacement. The pattern can be a string or a RegExp, and the replacement can be a string or a function to be called for each match. Crucially, if the pattern is a string, only the first occurrence will be replaced. To replace all occurrences, a regular expression with the global (g) flag must be used. This method is non-mutating and returns a fresh string instance, which is important for performance considerations in high-frequency operations where memory allocation might become a bottleneck. When using a function as the replacement, it is invoked for every match found, receiving the match, capture groups, and offsets as arguments. Edge cases include passing non-string patterns (which are coerced to strings) and handling special replacement patterns like & (the whole match) orn (parenthesized capture groups) inside the replacement string.

Quick reference

Syntax

string.replace(searchValue, replaceValue)

Inputs

Parameters

searchValuestring | RegExp · What to replace.
replaceValuestring | Function · Replacement string or function.

See it in practice

Examples

1

Basic String Replacement

const message = 'Hello World';
const updated = message.replace('World', 'JavaScript');
console.log(updated);
Output:
'Hello JavaScript'

A simple string-to-string replacement that only affects the first match found.

2

Global Regex Replacement

const text = 'blue house, blue car, blue sky';
const result = text.replace(/blue/g, 'red');
console.log(result);
Output:
'red house, red car, red sky'

Using a regular expression with the global /g flag to ensure all instances of the word are replaced.

3

Using a Replacer Function

const prices = 'Items: 10, 25, and 40 dollars';
const doubled = prices.replace(/\d+/g, function(match) {
  return parseInt(match) * 2;
});
console.log(doubled);
Output:
'Items: 20, 50, and 80 dollars'

A function is used to dynamically transform each match (in this case, doubling numbers).

Debug faster

Common Errors

1

LogicError

Cause: Expecting a string pattern to replace all occurrences instead of just the first.

Fix: Use a regular expression with the global (/g) flag or the replaceAll() method.

'apple apple'.replace('apple', 'orange'); // Returns 'orange apple'
2

ReferenceError

Cause: Misunderstanding capture groups in the replacement string (e.g., using $1 when no groups are defined in the regex).

Fix: Ensure the regular expression contains parentheses () to define capture groups for $1, $2, etc.

'JS'.replace(/JS/, '$1 Rocks'); // Returns '$1 Rocks' because no group was captured

Runtime support

Compatibility

Node.js, BrowserAll browsersES3+

Source: MDN Web Docs

Common questions

Frequently Asked Questions

Replaces the first match of a string/regex and returns a new string.

searchValue: What to replace. replaceValue: Replacement string or function.

LogicError: Use a regular expression with the global (/g) flag or the replaceAll() method. ReferenceError: Ensure the regular expression contains parentheses () to define capture groups for 2, etc.