JavaScript Reference ยท String
String.prototype.replace()
Reference for JavaScript String.prototype.replace(): replace the first match of a string or regular expression, use $ patterns and replacer functions.
The replace() method returns a new string in which a match of a pattern is replaced by a replacement. The pattern can be a string or a regular expression. The replacement can be a string, which may contain special $ patterns, or a function that computes the text for each match.
With a string pattern only the first occurrence is replaced. To replace every occurrence, use a regular expression with the g flag, or call replaceAll(). The original string is never changed, because strings are immutable.
"2026-10-23".replace("-", "/"); // "2026/10-23"
Try it
Press Run (or Ctrl + Enter) to see the console output here.
No output.
Press Run (or Ctrl + Enter) to see the console output here.
No output.
Syntax
string.replace(pattern, replacement)
| Name | Description |
|---|---|
pattern |
A string, or an object with a Symbol.replace method such as a regular expression. A string is matched literally; it is not turned into a regular expression. |
replacement |
A string, or a function. In a string, $$ is a dollar sign, $& the matched text, $` the text before the match, $' the text after it, $1...$99 a capture group, and $<name> a named group. |
A replacer function is called for each match with these arguments: the matched text, one argument per capture group, the offset of the match, the whole string, and, when the regular expression has named groups, a final object of groups. Its return value is converted to a string.
Return value: a new string with the replacement applied.
Exceptions: none for ordinary use. A TypeError can occur only in unusual cases, such as calling the method on null or undefined.
Usage notes
- Only the first match is replaced for a string pattern, and for a regular expression without
g. Add thegflag to replace all matches. - A string pattern is literal.
"a.b".replace(".", "-")replaces the first dot, not the first character. Special characters need escaping only inside a regular expression. $in the replacement is special. If the replacement comes from user input, a value such as$&is expanded. Use a function (() => value) to insert text exactly as it is.- Function arguments vary in number with the count of capture groups, so use rest parameters (
(...args)) if you need the last arguments reliably. - Case conversion is a common use: replace with a function that calls
toUpperCase()on the match or on a capture group. - Empty pattern:
"abc".replace("", "-")inserts at the start, giving"-abc". - Sticky and global regular expressions use and update
lastIndex; with thegflag,replace()resets it to0first, so the call behaves the same every time. - Not in place: forgetting to use the return value is a very common bug, because the original string stays the same.
Browser support
String.prototype.replace() has worked in every browser for a very long time, including named groups and $<name> patterns in current browsers.