A named capturing group is a particular kind of capturing group that allows to give a name to the group. The group's matching result can later be identified by this name instead of by its index in the pattern.
A named capturing group is a particular kind of capturing group that allows to give a name to the group. The group's matching result can later be identified by this name instead of by its index in the pattern.
(?<name>pattern)
pattern
A pattern consisting of anything you may use in a regex literal, including a disjunction.
name
The name of the group. Must be a valid identifier.
Named capturing groups can be used just like capturing groups — they also have their match index in the result array, and they can be referenced through \1
, \2
, etc. The only difference is that they can be additionally referenced by their name. The information of the capturing group's match can be accessed through:
groups
property of the return value of RegExp.prototype.exec()
, String.prototype.match()
, and String.prototype.matchAll()
groups
parameter of the String.prototype.replace()
and String.prototype.replaceAll()
methods' replacement
callback functionAll names must be unique within the same pattern. Multiple named capturing groups with the same name result in a syntax error.
/(?<name>)(?<name>)/; // SyntaxError: Invalid regular expression: Duplicate capture group name
This restriction is relaxed if the duplicate named capturing groups are not in the same disjunction alternative, so for any string input, only one named capturing group can actually be matched. This is a much newer feature, so check browser compatibility before using it.
/(?<year>\d{4})-\d{2}|\d{2}-(?<year>\d{4})/; // Works; "year" can either come before or after the hyphen
Named capturing groups will all be present in the result. If a named capturing group is not matched (for example, it belongs to an unmatched alternative in a disjunction), the corresponding property on the groups
object has value undefined
.
/(?<ab>ab)|(?<cd>cd)/.exec("cd").groups; // [Object: null prototype] { ab: undefined, cd: 'cd' }
You can get the start and end indices of each named capturing group in the input string by using the d
flag. In addition to accessing them on the indices
property on the array returned by exec()
, you can also access them by their names on indices.groups
.
Compared to unnamed capturing groups, named capturing groups have the following advantages:
The following example parses a timestamp and an author name from a Git log entry (output with git log --format=%ct,%an -- filename
):
function parseLog(entry) { const { author, timestamp } = /^(?<timestamp>\d+),(?<author>.+)$/.exec( entry, ).groups; return `${author} committed on ${new Date( parseInt(timestamp) * 1000, ).toLocaleString()}`; } parseLog("1560979912,Caroline"); // "Caroline committed on 6/19/2019, 5:31:52 PM"
Specification |
---|
ECMAScript Language Specification # prod-Atom |
Desktop | Mobile | Server | ||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
Chrome | Edge | Firefox | Opera | Safari | Chrome Android | Firefox for Android | Opera Android | Safari on IOS | Samsung Internet | WebView Android | Deno | Node.js | ||
Named_capturing_group |
64 | 79 | 78 | 51 | 11.1 | 64 | 79 | 47 | 11.3 | 9.0 | 64 | 1.0 | 10.0.0 | |
duplicate_named_capturing_groups |
No | No | No | No | preview | No | No | No | No | No | No | No | No |
© 2005–2023 MDN contributors.
Licensed under the Creative Commons Attribution-ShareAlike License v2.5 or later.
https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Regular_expressions/Named_capturing_group