JavaScript String replace() Method

Beginner
5 min read
Updated: Nov 2026
3 examples
Method
Decorative image with the word REPLACE

Definition

String.prototype.replace(pattern, replacement) returns a new string with matches swapped out. A plain string pattern replaces only the first match. A RegExp with g can replace every match.

Pass the required arguments shown below. Check return values and browser support before you rely on the result.

Syntax

Call string.replace. Start with this line.

JavaScript
str.replace(pattern, replacement)
CallWhat it does
str.replace(pattern, replacement)Primary signature.
string.replace(...)Call with the arguments your case needs.

Built into JavaScript. Call replace(...) on a string (or String instance) — no import required.

Library declarations
JavaScript
str.replace(pattern, replacement)

Parameters

ParameterDescription
patternRequired. Substring or RegExp to find
replacementRequired. New text, or a function returning text

Return Value

Return ValueDescription
*The value returned by string.replace().

JavaScript Examples

Example 1 — Replace the First Match

A plain string pattern swaps only the first occurrence.

JavaScript
const text = "hello world, world";

console.log(text.replace("world", "JS"));
// "hello JS, world"

console.log(text);
// "hello world, world"  (original unchanged)
Try It Yourself

How It Works

  1. Search for a literal. "world" is treated as plain text, not a regex.
  2. Swap the first hit. Only the first "world" becomes "JS".
  3. Leave the rest. The second "world" stays put.
  4. Keep the original. text is unchanged — use the return value.

Example 2 — Replace Every Match with /g

Add the global flag (and i for case-insensitive).

JavaScript
const str = "Apples are round, and apples are juicy.";

console.log(str.replace(/apples/gi, "oranges"));
// "oranges are round, and oranges are juicy."

console.log("a a a".replace(/a/g, "b"));
// "b b b"
Try It Yourself

How It Works

  1. Use a RegExp. Plain strings cannot replace every match with replace().
  2. Add g. Global mode walks the whole string.
  3. Add i when needed. /apples/gi matches "Apples" and "apples".
  4. Prefer replaceAll for clarity. For “all of these,” see replaceAll().

Example 3 — Capture Groups with $1 / $2

Reorder parts of a match using capturing groups.

JavaScript
const name = "Maria Cruz";

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

console.log("2024-10-02".replace(/(\d{4})-(\d{2})-(\d{2})/, "$2/$3/$1"));
// "10/02/2024"
Try It Yourself

How It Works

  1. Capture with parentheses. (\w+) is group 1; the next (\w+) is group 2.
  2. Reuse in the replacement. $1 and $2 insert those groups.
  3. Reorder freely. "$2, $1" puts last name first.
  4. Same idea for dates. Year/month/day groups rearrange into MM/DD/YYYY.
Compatibility

Browser & Runtime Support

String.prototype.replace() has been in JavaScript since the early language and is universal across browsers and runtimes.

✓ Baseline · Universal

String.prototype.replace()

Supported in all modern browsers, Internet Explorer, and every current Node.js release. Safe everywhere.

100% Browser support
Google Chrome Supported · Desktop & Mobile
Full support
Mozilla Firefox Supported · Desktop & Mobile
Full support
Apple Safari Supported · macOS & iOS
Full support
Microsoft Edge Supported · Chromium
Full support
Internet Explorer No native support · Use a polyfill
Polyfill
Opera Supported · Modern versions
Full support
Samsung Internet Supported · Android
Full support
Bun Supported · JavaScript runtime
Supported
Deno Supported · JavaScript runtime
Supported
Node.js Supported · Server runtime
Supported
Android WebView Supported · Modern WebView
Full support
String.replace() Universal

Bottom line: Use confidently in any environment. For replacing every string match with a clearer API, prefer replaceAll() where available (ES2021+).

Frequently Asked Questions

replace(pattern, replacement) returns a new string where matches of pattern are swapped for replacement. A plain string pattern replaces only the first match. A RegExp with the g flag can replace every match.
No. Strings are immutable. replace() returns a new string; the original stays the same.
Use a regular expression with the g (global) flag, or use String.prototype.replaceAll() for a clearer all-matches API.
Yes. Pass a function as the second argument. It runs for each match and its return value becomes the replacement text.
When pattern is a RegExp with capturing groups, $1 inserts the first group, $2 the second, and so on. $$ inserts a literal dollar sign. $& inserts the whole match.
replace() returns a new string with the same contents as the original — nothing is changed.

Next: replaceAll()

Learn the clearer API for replacing every match in a string.

replaceAll() tutorial →

About the author

Mari Selvan M P
Mari Selvan M P 🔗

Developer, cloud engineer, and technical writer

  • Experience 12 years building web and cloud systems
  • Focus Full Stack Development, AWS, and Developer Education

I write practical tutorials so students and working developers can learn by doing—from databases and APIs to deployment on AWS.

AWS Certified Developer – Associate (Credly)

11 people found this page helpful

JavaScript String repeat() Method JavaScript String replaceAll() Method