JavaScript String matchAll() Method

What You’ll Learn

String.prototype.matchAll() returns an iterator of every regex match, including capturing groups (same API as MDN String.prototype.matchAll()). Learn the required g flag, how it beats global match() for groups, how it replaces exec() loops, lastIndex safety, five examples, and try-it labs.

Introduction

match() with the g flag gives you every full match as plain strings — but it drops capturing groups. When you need groups for every hit, use matchAll().

It returns an iterator (not an array). Use for...of, spread ([...]), or Array.from() to consume it. Each yielded value looks like RegExp.prototype.exec(): full match, groups, index, and input.

This page is part of JavaScript String Methods. Related topics include match() and includes().

Understanding the matchAll() Method

Under the hood, str.matchAll(regexp) validates that a RegExp is global, then calls its Symbol.matchAll method (implemented by RegExp.prototype[Symbol.matchAll]).

• Requires the g flag on a real RegExp.
• Yields one exec()-shaped array per match (groups included).
• Iterator is not restartable — call matchAll() again to rescan.
• Clones the regex, so your lastIndex is left alone.

📝 Syntax

General form of String.prototype.matchAll:

str.matchAll(regexp)

Parameters

• regexp — a RegExp with the g flag, or any object with Symbol.matchAll. Other values become new RegExp(regexp, "g").

Return value

An iterable iterator of match arrays (empty if nothing matches):

Common patterns

const re = /t(e)(st(\d?))/g;
const hits = [..."test1test2".matchAll(re)];
hits[0][0];  // "test1"
hits[0][1];  // "e"
hits[1][0];  // "test2"

// for...of (iterator is exhausted afterward):
for (const m of "table football".matchAll(/foo[a-z]*/g)) {
  console.log(m[0], m.index);
}

// Collect full match strings only:
Array.from("a1b2".matchAll(/(\d)/g), (m) => m[0]);  // ["1", "2"]

Examples Gallery

Examples follow MDN String.matchAll() patterns. Use View Output or Try It Yourself for each case.

const regexp = /t(e)(st(\d?))/g;
const str = "test1test2";

const array = [...str.matchAll(regexp)];

array[0];
// ["test1", "e", "st1", "1", index: 0, input: "test1test2", ...]

array[1];
// ["test2", "e", "st2", "2", index: 5, input: "test1test2", ...]

test1 | e | st1 | 1 | index=0
test2 | e | st2 | 2 | index=5

const regexp = /foo[a-z]*/g;
const str = "table football, foosball";

for (const match of str.matchAll(regexp)) {
  console.log(
    `Found ${match[0]} start=${match.index} end=${
      match.index + match[0].length
    }.`
  );
}
// Found football start=6 end=14.
// Found foosball start=16 end=24.

Array.from(str.matchAll(regexp), (m) => m[0]);
// ["football", "foosball"]

Found football start=6 end=14.
Found foosball start=16 end=24.
football,foosball

const regexp = /t(e)(st(\d?))/g;
const str = "test1test2";

str.match(regexp);
// ["test1", "test2"]  — groups missing!

const array = [...str.matchAll(regexp)];
array[0];  // ["test1", "e", "st1", "1", ...]
array[1];  // ["test2", "e", "st2", "2", ...]

match: test1,test2
matchAll[0]: test1 | e | st1 | 1
matchAll[1]: test2 | e | st2 | 2

try {
  [..."abc".matchAll(/[a-c]/)];  // no g
} catch (e) {
  console.log(e.name);  // TypeError
}

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"]  — lastIndex still 1

TypeError
1 b
1 c

const text = "fox jumps over the cat";
const re = /(?<animal>fox|cat)/g;

const animals = [...text.matchAll(re)].map((m) => m.groups.animal);
// ["fox", "cat"]

[..."none".matchAll(/xyz/g)];  // []  (empty — not null)

fox,cat
[]

🚀 Common Use Cases

• Parse repeating patterns — IDs, tokens, tags with groups on each hit.
• Replace exec loops — cleaner for...of over matches.
• Named captures at scale — map m.groups across the string.
• Keep lastIndex intact — safe when the same regex is reused elsewhere.
• Not for yes/no — use regex.test(str).
• Not for full strings only — global match() is simpler then.

📝 Notes

• A RegExp without g throws TypeError.
• No matches → empty iterator (not null).
• The iterator is not restartable after you finish iterating.
• Unlike an exec loop, you cannot steer progress by mutating lastIndex.
• Global match() is still fine when you only need full match strings.
• Baseline widely available since January 2020.

💡 Best Practices