Replacing a substring in JavaScript means creating a new string where part of the original text is changed. JavaScript strings are immutable, so methods such as replace() and replaceAll() return a new string and leave the original value unchanged.
Use replace() for one match or regex-based replacements. Use replaceAll() when every exact substring should be replaced.
Environment: Node.js v20.18.2. After each runnable snippet, the following paragraph states the expected console output (order and values).
Method 1: Replace One Substring with replace()
When replace() receives a string as the first argument, it replaces only the first match.
const message = "Hello user, user";
const result = message.replace("user", "Ana");
console.log("replace-one:", result);You should see one line logging replace-one: Hello Ana, user.
This is useful when only the first occurrence should change.
Method 2: Replace All Substrings with replaceAll()
Use replaceAll() to replace every exact substring match.
const message = "Hello user, user";
const result = message.replaceAll("user", "Ana");
console.log("replace-all:", result);You should see one line logging replace-all: Hello Ana, Ana.
replaceAll() is straightforward for plain text replacement where regex is not needed.
Method 3: Replace a Pattern with a Regular Expression
Use a regular expression when the target substring follows a pattern.
const order = "Order 123";
const result = order.replace(/\d+/, "#");
console.log("replace-regex:", result);You should see one line logging replace-regex: Order #.
The pattern /\d+/ matches one or more digits.
Method 4: Replace Every Regex Match
Add the global g flag to replace every regex match.
const text = "ID 123, ZIP 456";
const result = text.replace(/\d+/g, "#");
console.log(result);You should see one line logging ID #, ZIP #.
Without g, only the first regex match is replaced.
Method 5: Use a Replacement Function
The second argument to replace() can be a function. This is useful when the replacement depends on the matched value.
const result = "item-2 item-9".replace(/\d+/g, (match) => String(Number(match) + 1));
console.log(result);You should see one line logging item-3 item-10.
Use this pattern for formatting, incrementing numbers, masking values, or normalizing text.
Common Questions About Replacing Substrings
How do I replace all occurrences of a substring in JavaScript?
Use replaceAll("old", "new") for plain text, or replace(/old/g, "new") for regular expressions.
Does replace change the original string?
No. JavaScript strings are immutable. replace() and replaceAll() return a new string.
Why did replace only change the first match?
That is the default behavior of replace() with a string or non-global regex. Use replaceAll() or a regex with the g flag for every match.
Summary
Use replace() to replace one substring or a regex match in JavaScript. Use replaceAll() for every exact substring occurrence, and use a global regular expression when the replacement target is pattern-based. For dynamic replacements, pass a function as the second argument so each match can be transformed before the new string is returned.
