The JavaScript string.replace() method

Q: How do I replace all occurrences in a string?

Use str.replaceAll("x", "y") or a global regex: str.replace(/x/g, "y").

Q: Does replace() change the original string?

No. Strings are immutable; replace() returns a new string and the original stays the same.

Q: How do I do a case-insensitive replace?

Use a regex with the i flag, e.g. str.replace(/hello/gi, "hi").

Method JavaScript All modern browsers Updated June 23, 2026

Quick answer

The replace() method returns a new string with the first match of a pattern swapped out. "a-b-c".replace("-", "+") gives "a+b-c" — note only the first dash changed. To replace every match, use a regex with the global flag (/-/g) or the newer replaceAll(). The original string is never changed.

Overview

replace() swaps text for other text and hands you back a new string. The thing that catches everyone out is that, given a plain string to search for, it only replaces the first match. "1-2-3".replace("-", "") removes just the first dash, leaving "12-3". If you expected all of them gone, this is why.

To replace every occurrence, you have two options. Pass a regular expression with the global flag — str.replace(/-/g, "") — or use the clearer modern method replaceAll(), which does what its name says. Regexes also unlock pattern matching and capture groups, where $1, $2 reference matched parts in the replacement.

The replacement can even be a function, called for each match, which is powerful for dynamic substitutions. Whatever you do, remember strings are immutable: replace() returns a new string and leaves the original alone, so you must use the return value.

Syntax

const result = str.replace(pattern, replacement)

"a-b-c".replace("-", "+")     // "a+b-c"  (first only)
"a-b-c".replace(/-/g, "+")     // "a+b+c"  (all, with /g)

Parameters

The string.replace() method accepts the following parameters.

Parameter	Description
`pattern`	A string (matches the first occurrence) or a regular expression (use the `g` flag to match all).
`replacement`	The replacement string (where `$1`, `$&` reference the match) or a function returning the replacement.

Example

Live example

<pre id="out" style="font:15px ui-monospace,monospace"></pre>
<script>
  const phone = '555-123-4567';

  const first = phone.replace('-', '');     // first dash only
  const all   = phone.replace(/-/g, '');    // every dash

  document.getElementById('out').textContent =
    'first: ' + first + '\n' +
    'all:   ' + all; // first: 555123-4567 / all: 5551234567
</script>

Best practices

Remember a string pattern replaces only the first match — use a /g regex or replaceAll() for all.
Always use the return value; strings are immutable, so the original is unchanged.
Use a regex when you need patterns, capture groups ($1) or case-insensitive matching (/i).
Pass a function as the replacement when each match needs custom logic.

Frequently asked questions

Why does replace() only change the first match?

With a plain string pattern it replaces a single occurrence. To replace all, use a global regex (/x/g) or replaceAll().

How do I replace all occurrences in a string?

Use str.replaceAll("x", "y") or a global regex: str.replace(/x/g, "y").

Does replace() change the original string?

No. Strings are immutable; replace() returns a new string and the original stays the same.

How do I do a case-insensitive replace?

Use a regex with the i flag, e.g. str.replace(/hello/gi, "hi").

string.repeat() string.replaceAll()

References