String.prototype.matchAll()
The matchAll() method returns an iterator of all results matching a string against a regular expression, including capturing groups.
Try it
Syntax
matchAll(regexp)
Parameters
 regexp  A regular expression object, or any object that has a Symbol.matchAll method. If regexp is not a RegExp object and does not have a Symbol.matchAll method, it is implicitly converted to a RegExp by using new RegExp(regexp, 'g'). If regexp is a regex, then it must have the global (g) flag set, or a TypeError is thrown.  Return value
An iterable iterator (which is not restartable) of matches. Each match is an array with the same shape as the return value of RegExp.prototype.exec().Exceptions
 TypeError  Thrown if the regexp is a regex that does not have the global (g) flag set (its flags property does not contain "g").  Description
The implementation of String.prototype.matchAll itself is very simple — it simply calls the Symbol.matchAll method of the argument with the string as the first parameter (apart from the extra input validation that the regex is global). The actual implementation comes from RegExp.prototype[@@matchAll]().Examples
Regexp.prototype.exec() and matchAll()

Without matchAll(), it's possible to use calls to regexp.exec() (and regexes with the g flag) in a loop to obtain all the matches: const regexp = /foo[a-z]*/g;
const str = 'table football, foosball';
let match;

while ((match = regexp.exec(str)) !== null) {
  console.log(`Found ${match[0]} start=${match.index} end=${regexp.lastIndex}.`);
  // expected output: "Found football start=6 end=14."
  // expected output: "Found foosball start=16 end=24."
}
 With matchAll() available, you can avoid the while loop and exec with g. Instead, you get an iterator to use with the more convenient for...of, array spreading, or Array.from() constructs: const regexp = /foo[a-z]*/g;
const str = 'table football, foosball';
const matches = str.matchAll(regexp);

for (const match of matches) {
  console.log(`Found ${match[0]} start=${match.index} end=${match.index + match[0].length}.`);
}
// expected output: "Found football start=6 end=14."
// expected output: "Found foosball start=16 end=24."

// matches iterator is exhausted after the for...of iteration
// Call matchAll again to create a new iterator
Array.from(str.matchAll(regexp), (m) => m[0]);
// Array [ "football", "foosball" ]
 matchAll will throw an exception if the g flag is missing. const regexp = /[a-c]/;
const str = 'abc';
str.matchAll(regexp);
// TypeError
 matchAll internally makes a clone of the regexp — so, unlike regexp.exec(), lastIndex does not change as the string is scanned. const regexp = /[a-c]/g;
regexp.lastIndex = 1;
const str = 'abc';
Array.from(str.matchAll(regexp), (m) => `${regexp.lastIndex}${m[0]}`);
// Array [ "1 b", "1 c" ]
 However, this means that unlike using regexp.exec() in a loop, you can't mutate lastIndex to make the regex advance or rewind.
Better access to capturing groups (than String.prototype.match())

Another compelling reason for matchAll is the improved access to capture groups. Capture groups are ignored when using match() with the global g flag: const regexp = /t(e)(st(\d?))/g;
const str = 'test1test2';

str.match(regexp);
// Array ['test1', 'test2']
 Using matchAll, you can access capture groups easily: const array = [...str.matchAll(regexp)];

array[0];
// ['test1', 'e', 'st1', '1', index: 0, input: 'test1test2', length: 4]
array[1];
// ['test2', 'e', 'st2', '2', index: 5, input: 'test1test2', length: 4]

Using matchAll() with a non-RegExp implementing @@matchAll

If an object has a Symbol.matchAll method, it can be used as a custom matcher. The return value of Symbol.matchAll becomes the return value of matchAll(). const str = "Hmm, this is interesting.";

str.matchAll({
  [Symbol.matchAll](str) {
    return [["Yes, it's interesting."]];
  }
}); // returns [["Yes, it's interesting."]]

Specifications

Specification
ECMAScript Language Specification # sec-string.prototype.matchall

Browser compatibility




Desktop
Mobile
Server



Chrome
Edge
Firefox
Internet Explorer
Opera
Safari
WebView Android
Chrome Android
Firefox for Android
Opera Android
Safari on IOS
Samsung Internet
Deno
Node.js



matchAll
73
79
67
No
60
13
73
73
67
52
13
11.0
1.0
12.0.0


See also
 Polyfill of String.prototype.matchAll in core-js String.prototype.match() Using regular expressions in JavaScript Capturing groups RegExp RegExp.prototype.exec() RegExp.prototype.test() RegExp.prototype[@@matchAll]() 

Found a problem with this page?

Edit on GitHub
Source on GitHub
Report a problem with this content on GitHub
Want to fix the problem yourself? See our Contribution guide.


Last modified: Sep 5, 2022, by MDN contributors


    
{'path': 'public/docs/javascript/global_objects/string/matchall.html', 'source': 'DevDocs.IO'}