JavaScript String replace() Method

What You’ll Learn

String.prototype.replace() returns a new string with matches of a pattern swapped for a replacement (same API as MDN String.prototype.replace()). Learn string vs regex patterns, the g flag, capture groups, replacer functions, five examples, and try-it labs.

Introduction

Need to swap one word for another, clean up a pattern, or rewrite part of a string with logic? replace() builds a new string from the old one by substituting matches.

Pass a string as the pattern and only the first match is replaced. Pass a RegExp with the g flag to replace every match. The second argument can be a plain string (with special $ patterns) or a function.

This page is part of JavaScript String Methods. Related topics include match() and repeat().

Understanding the replace() Method

str.replace(pattern, replacement) searches str for pattern and returns a new string with matches rewritten.

• A string pattern replaces only the first occurrence.
• A RegExp without g also replaces only the first match.
• A RegExp with g replaces every match.
• replacement may be a string or a function.
• The original string is never modified.

📝 Syntax

General form of String.prototype.replace:

str.replace(pattern, replacement)

Parameters

• pattern — a string, or a RegExp (any object with Symbol.replace). Non-regex values are coerced to strings.
• replacement — a string (may include $&, $1, …) or a function called for each match.

Return value

A string with matches replaced:

Useful replacement patterns (string replacement)

Common patterns

"cat cat".replace("cat", "dog");     // "dog cat"
"cat cat".replace(/cat/g, "dog");    // "dog dog"

"Xmas".replace(/xmas/i, "Christmas"); // "Christmas"

"Maria Cruz".replace(/(\w+)\s(\w+)/, "$2, $1");
// "Cruz, Maria"

Examples Gallery

Examples follow MDN String.replace() patterns. Use View Output or Try It Yourself for each case.

const paragraph = "This dog's name is just Dog! Yes, that is the name.";

paragraph.replace("name", "nickname");
// "This dog's nickname is just Dog! Yes, that is the name."

paragraph.replace(/\bis\b/, "was");
// "This dog's name was just Dog! Yes, that is the name."

paragraph.replace(/\bis\b/g, "was");
// "This dog's name was just Dog! Yes, that was the name."

This dog's nickname is just Dog! Yes, that is the name.
This dog's name was just Dog! Yes, that is the name.
This dog's name was just Dog! Yes, that was the name.

const str = "Twas the night before Xmas...";
const newStr = str.replace(/xmas/i, "Christmas");

newStr;
// "Twas the night before Christmas..."

Twas the night before Christmas...

const re = /apples/gi;
const str = "Apples are round, and apples are juicy.";
const newStr = str.replace(re, "oranges");

newStr;
// "oranges are round, and oranges are juicy."

oranges are round, and oranges are juicy.

const re = /(\w+)\s(\w+)/;
const str = "Maria Cruz";
const newStr = str.replace(re, "$2, $1");

newStr;
// "Cruz, Maria"

Cruz, Maria

function styleHyphenFormat(propertyName) {
  return propertyName.replace(/[A-Z]/g, function (match, offset) {
    return (offset > 0 ? "-" : "") + match.toLowerCase();
  });
}

styleHyphenFormat("borderTop");
// "border-top"

styleHyphenFormat("backgroundColor");
// "background-color"

border-top
background-color

🚀 Common Use Cases

• Fix one typo / token — swap the first occurrence of a word.
• Global cleanup — regex with g (or replaceAll) for every match.
• Case-insensitive edits — add the i flag.
• Reorder parts — capture groups with $1 / $2.
• Dynamic transforms — pass a function for per-match logic.
• Not for reading matches — use match() / matchAll() when you only need the hits.

📝 Notes

• A string pattern replaces only the first match.
• Only a regex with the g flag replaces multiple times via replace().
• Special $ patterns work in string replacements, not in values returned from a function.
• Empty string pattern prepends the replacement: "xxx".replace("", "_") → "_xxx".
• Prefer replaceAll() when you clearly want every literal occurrence.
• Always capture the return value — the original string does not update in place.

💡 Best Practices