Single literal substitution
Replace a known literal prefix or token once.
JavaScript · Function
replace
String.prototype.replace() returns a new string with matching text replaced. String patterns replace only the first occurrence; use a global regular expression or replaceAll() for all occurrences.
How it works
Call replace() on a string with a string or pattern to search and a string or callback to generate replacement text. It returns a new string, leaving the original unchanged; a string pattern affects only its first occurrence, while a regular expression with the g flag can replace every match.
Syntax
replace(pattern, replacement)Parameters
| Name | Type | Description |
|---|---|---|
pattern | string | RegExp | object | The search value: a string, a regular expression, or an object providing Symbol.replace; values without that method are converted to strings. |
replacement | string | function | Replacement text, or a function called for each match whose return value supplies the replacement text. |
Returns
A new string with one, some, or all matches of the pattern replaced by the specified replacement.
Key points
- replace() produces a new string containing the requested substitutions.
- Both search patterns and replacement behavior support two forms: strings or regular expressions for matching, and strings or callbacks for replacement.
- Choose a global regular expression or replaceAll() when the operation must cover all matches.
- String replacements can interpret tokens such as $$, $&, $
, and $' to insert special text. - The second argument may compute replacement text independently for each match.
Common mistakes
- A string pattern does not replace every occurrence; use a global regular expression or replaceAll() when all occurrences are needed.
- Do not expect replace() to mutate the source string; assign the returned value if the updated text must be retained.
- A replacement callback runs once per match, so its arguments and returned text determine each substitution.
Example: Reorder captured date parts
const input = "2024-07-15";
const formatted = input.replace(/^(\d{4})-(\d{2})-(\d{2})$/, "$2/$3/$1");
console.log(formatted); // "07/15/2024"A regular expression captures the date parts, and replacement tokens insert them in month/day/year order.
When to use it
Pattern-based rewriting
Transform every match with regular expressions and capture groups.
Computed replacements
Generate replacement text from match data.
Interview questions
QWhat does String.prototype.replace() return and accept?
replace(pattern, replacement) returns a new string with matching text substituted. The pattern may be a string or an object implementing Symbol.replace, and the replacement may be a string or function.
Follow-up: How can every occurrence of a literal substring be replaced? Use replaceAll(), or use a regular expression with the global g flag.
QHow does replacement count differ for string and RegExp patterns?
A string pattern is searched only once, so only its first occurrence is replaced. A global regular expression can match multiple occurrences.
Follow-up: What happens if the original string is not assigned the result? The source remains unchanged, because strings and this method do not mutate it.
QWhen should the replacement argument be a function?
A replacement function is called for each match, and its return value becomes that match's replacement text. This is useful when replacement content depends on the matched text or captures.
Follow-up: How can captured groups be used? Define capturing groups in the regular expression and read the corresponding callback arguments, then construct the returned replacement.
Related
String.prototype.replaceAll()RegExp.prototype[Symbol.replace]()Symbol.replaceString.prototype.match()String.prototype.matchAll()