RegExp.prototype[Symbol.matchAll]()
Baseline
Widely available
This feature is well established and works across many devices and browser versions. It’s been available across browsers since January 2020.
The [Symbol.matchAll]() method of String.prototype.matchAll should behave.
Try it
class MyRegExp extends RegExp {
[Symbol.matchAll](str) {
const result = RegExp.prototype[Symbol.matchAll].call(this, str);
if (!result) {
return null;
}
return Array.from(result);
}
}
const re = new MyRegExp("-\\d+", "g");
console.log("2016-01-02|2019-03-07".matchAll(re));
/ Expected output: Array [Array ["-01"], Array ["-02"], Array ["-03"], Array ["-07"]]
Syntax
regexp[Symbol.matchAll](str)
Parameters
Return value
Description
This method is called internally in String.prototype.matchAll(). For example, the following two examples return the same result.
"abc".matchAll(/a/g);
/a/g[Symbol.matchAll]("abc");
Like lastIndex starts as the original regex's value.
const regexp = /[a-c]/g;
regexp.lastIndex = 1;
const str = "abc";
Array.from(str.matchAll(regexp), (m) => `${regexp.lastIndex} ${m[0]}`);
/ [ "1 b", "1 c" ]
The validation that the input is a global regex happens in exec() is called and the result is yielded.
When the regex is sticky and global, it will still perform sticky matches — i.e., it will not match any occurrences beyond the lastIndex.
console.log(Array.from("ab-c".matchAll(/[abc]/gy)));
/ [ [ "a" ], [ "b" ] ]
If the current match is an empty string, the u flag, it advances by one Unicode code point; otherwise, it advances by one UTF-16 code point.
console.log(Array.from("😄".matchAll(/(?:)/g)));
/ [ [ "" ], [ "" ], [ "" ] ]
console.log(Array.from("😄".matchAll(/(?:)/gu)));
/ [ [ "" ], [ "" ] ]
This method exists for customizing the behavior of matchAll() in RegExp subclasses.
Examples
Direct call
This method can be used in almost the same way as String.prototype.matchAll(), except for the different value of this and the different order of arguments.
const re = /\d+/g;
const str = "2016-01-02";
const result = re[Symbol.matchAll](str);
console.log(Array.from(result, (x) => x[0]));
/ [ "2016", "01", "02" ]
Using [Symbol.matchAll]() in subclasses
Subclasses of RegExp can override the [Symbol.matchAll]() method to modify the default behavior.
For example, to return an iterator:
class MyRegExp extends RegExp {
[Symbol.matchAll](str) {
const result = RegExp.prototype[Symbol.matchAll].call(this, str);
return result ? Array.from(result) : null;
}
}
const re = new MyRegExp("(\\d+)-(\\d+)-(\\d+)", "g");
const str = "2016-01-02|2019-03-07";
const result = str.matchAll(re);
console.log(result[0]);
/ [ "2016-01-02", "2016", "01", "02" ]
console.log(result[1]);
/ [ "2019-03-07", "2019", "03", "07" ]
Specifications
| Specification |
|---|
| ECMAScript® 2026 Language Specification # sec-regexp-prototype-%symbol.matchall% |