CKTIS / JavaScript
RegExp named capture groups and replacement substitutions
Read captured text by name and reuse it in replacement strings or callbacks, including when an optional group does not match.
Version: ECMAScript 2024 and the current web platform; runtime support varies
Syntax
/(?<name>pattern)/
/(?<name>pattern)\k<name>/
regexp.exec(text)?.groups?.name
text.replace(regexp, "$<name>")
text.replace(regexp, replacer)
text.replaceAll(globalRegexp, replacement)
Replacement string tokens: $$, $&, $`, $', $1 … $99, $<name>RegExp named capture groups and replacement substitutions work together: (?<name>...) records the text matched by a subpattern, and a replacement can reuse that text. Named and unnamed captures share numbering from 1 in opening-parenthesis order; (?:...) does not capture. After a successful exec(), read the value with result.groups.name; a group that did not participate has value undefined. Inside the pattern, \k<name> is a backreference that matches captured text; it does not insert text into a replacement.
In a replacement string, $<name> inserts a named capture, $1 inserts the first capture, $& inserts the whole match, and $$ inserts a dollar sign. The tokens $` and $' insert the original text before and after the match, respectively. If the pattern has named groups, an unknown name or a group that did not participate inserts an empty string. Without named groups, $<name> stays literal. An existing but unmatched numbered capture also inserts an empty string; if group 12 does not exist, $12 can mean $1 followed by a literal 2, provided group 1 exists.
A replacer callback gets the whole match, the capture values in order, the offset in UTF-16 code units, the input string, and a final groups object only if the pattern has named groups. Unmatched captures are undefined. The callback result is not processed as a replacement template: use () => text to insert text containing $ literally.
With a standard RegExp, replace() replaces only the first match when neither g nor y is set, and all matches when g is set without y. With y but not g, it replaces at most one match, which must start at the current lastIndex. With gy, it starts at offset 0 and stops as soon as there is no match at the current position, without searching ahead. replaceAll() throws TypeError for a regular expression without g. Both return a result string without changing the input.
Group names follow identifier syntax. An invalid name is a SyntaxError, as is any duplicate name in ECMAScript 2024. ECMAScript 2025 permits duplicate names in separate branches of the same | disjunction. Check your target runtime's support; use unique names for ECMAScript 2024 compatibility.
Examples
const text = "AB-12 CD";
const token = /(?<code>[A-Z]{2})(?:-(?<number>\d+))?/g;
console.log(text.replace(token, "[$<code>:$<number>]"));
console.log(text.replace(token, (match, code, number, offset, input, groups) =>
`[${groups.code}:${groups.number ?? "none"}]`
));Result
[AB:12] [CD:] [AB:12] [CD:none]
For `CD`, the `number` group does not participate. The replacement string leaves that field empty, while the callback inserts `none`.
Related lessons
- JavaScript · Lesson 25 · Intermediate · Version: 3
Sources
- ECMAScript 2024 — GetSubstitution
- ECMAScript 2024 — RegExp.prototype [ %Symbol.replace% ]
- ECMAScript 2024 — RegExp Pattern Early Errors
- ECMAScript 2025 — MightBothParticipate
- Named capturing group: (?<name>...) - JavaScript | MDN
- Named backreference: \k<name> - JavaScript | MDN
- String.prototype.replace() - JavaScript | MDN
- String.prototype.replaceAll() - JavaScript | MDN