Skip to content
Tutorials Center
My learning

Topics

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.

JavaScript
"2026-10-23".replace("-", "/"); // "2026/10-23"

Try it

JS First match versus all matches

Press Run (or Ctrl + Enter) to see the console output here.

No output.

JS Replacement patterns and functions

Press Run (or Ctrl + Enter) to see the console output here.

No output.

Syntax

JavaScript
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 the g flag 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 the g flag, replace() resets it to 0 first, 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.