matchAll() JavaScript String Method – Explained with Examples

Whenever you use matchAll() on a string, the method does the following:

1. It creates an iterator object.
2. It populates the newly created iterator with all the patterns that match the method's regular expression argument.

note

• matchAll() matches all patterns—including capturing groups.
• matchAll() returns an iterator that is not restartable.
• matchAll() is sometimes written as String.prototype.matchAll() because it is a method of the String object's prototype property.

Syntax of the matchAll() Method

matchAll() accepts a regular expression argument. Here is the syntax:

string.matchAll(RegExp);

note

• Suppose matchAll()'s argument is a non-RegExp value—such as a string or a number. In that case, JavaScript will use the new RegExp(...) syntax to convert the argument to a regular expression.
• Suppose you do not provide an argument or if the regular expression argument does not match any pattern. In that case, the computer will return an empty iterator object.
• Always use a g flag with matchAll()'s RegExp argument. Otherwise, the computer will throw a TypeError.

Examples

Below are examples of the matchAll() method.

Use matchAll() to match a pattern that contains no capturing group

"Tuesday".matchAll(/day/g);

// The invocation above will return:
RegExp String Iterator {  }

Let's discuss converting the iterator in the snippet above to an array.

How to convert an iterator to an array object

The three typical ways to convert an iterator to an array object are by using:

1. Array.from()
2. for...of
3. Spread operator (...)

Let's discuss the three techniques.

How to use Array.from() to convert an iterator to an array object

// Assign a string to a variable:
const string = "Tuesday";

// Assign a regular expression to a variable:
const regExp = /day/g;

// Match the regular expression's pattern against the string and assign the result to a variable:
const iteratorResult = string.matchAll(regExp);

// Convert the iterator object to an array:
const arrayResult = Array.from(iteratorResult);

// Print the arrayResult variable's content on the console:
console.log(arrayResult);

// The invocation above will return:
[['day', index: 4, input: 'Tuesday', groups: undefined]]

In the returned array above,

• 'day' refers to the matched pattern.
• index refers to the index position where the matched pattern began.
• input indicates the string on which you invoked matchAll().
• groups contains a collection of the named capturing groups you specified in matchAll()'s RegExp argument. Or undefined if the regular expression does not contain any named capturing group.

Let's now see how to use the for...of loop to convert an iterator to an array object.

How to use for...of to convert an iterator to an array object

// Assign a string to a variable:
const string = "Tuesday";

// Assign a regular expression to a variable:
const regExp = /day/g;

// Match the regular expression's pattern against the string and assign the result to a variable:
const iteratorResult = string.matchAll(regExp);

// Convert the iterator object to an array:
for (const arrayResult of iteratorResult) {
  // Print the arrayResult variable's content on the console:
  console.log(arrayResult);
}

// The invocation above will return:
['day', index: 4, input: 'Tuesday', groups: undefined]

In the returned array above,

• 'day' refers to the matched pattern.
• index refers to the index position where the matched pattern began.
• input indicates the string on which you invoked matchAll().
• groups contains a collection of the named capturing groups you specified in matchAll()'s RegExp argument. Or undefined if the regular expression does not contain any named capturing group.

Let's now see how to use the spread operator to convert an iterator to an array object.

CodeSweetly ads

Create NPM Package like a pro

Learn the fundamentals of building and managing NPM packages from scratch.

Find out more

How to use the spread operator to convert an iterator to an array object

// Assign a string to a variable:
const string = "Tuesday";

// Assign a regular expression to a variable:
const regExp = /day/g;

// Match the regular expression's pattern against the string and assign the result to a variable:
const iteratorResult = string.matchAll(regExp);

// Convert the iterator object to an array:
const arrayResult = [...iteratorResult];

// Print the arrayResult variable's content on the console:
console.log(arrayResult);

// The invocation above will return:
[['day', index: 4, input: 'Tuesday', groups: undefined]]

In the returned array above,

• 'day' refers to the matched pattern.
• index refers to the index position where the matched pattern began.
• input indicates the string on which you invoked matchAll().
• groups contains a collection of the named capturing groups you specified in matchAll()'s RegExp argument. Or undefined if the regular expression does not contain any named capturing group.

Let's now see another example of the matchAll() method.

Use matchAll() to match a pattern containing a capturing group

// Assign a string to a variable:
const string = "Tuesday";

// Assign a regular expression to a variable:
const regExp = /d(a)y/g;

// Match the regular expression's pattern against the string and assign the result to a variable:
const iteratorResult = string.matchAll(regExp);

// Convert the iterator object to an array:
const arrayResult = [...iteratorResult];

// Print the arrayResult variable's content on the console:
console.log(arrayResult);

// The invocation above will return:
[['day', 'a', index: 4, input: 'Tuesday', groups: undefined]]

In the returned array above,

• 'day' refers to the matched pattern.
• 'a' indicates the matched capturing group pattern.
• index refers to the index position where the matched pattern began.
• input indicates the string on which you invoked matchAll().
• groups contains a collection of the named capturing groups you specified in matchAll()'s RegExp argument. Or undefined if the regular expression does not contain any named capturing group.

Let's now see another example of the matchAll() method.

Use matchAll() to match a pattern containing two capturing groups

// Assign a string to a variable:
const string = "It's a sunny Sunday!";

// Assign a regular expression to a variable:
const regExp = /(su)nd(a)y/gi;

// Match the regular expression's pattern against the string and assign the result to a variable:
const iteratorResult = string.matchAll(regExp);

// Convert the iterator object to an array:
const arrayResult = [...iteratorResult];

// Print the arrayResult variable's content on the console:
console.log(arrayResult);

// The invocation above will return:
[['Sunday', 'Su', 'a', index: 13, input: "It's a sunny Sunday!", groups: undefined]]

In the returned array above,

• 'Sunday' refers to the matched pattern.
• 'Su' indicates the first matched capturing group pattern.
• 'a' indicates the second matched capturing group pattern.
• index refers to the index position where the matched pattern began.
• input indicates the string on which you invoked matchAll().
• groups contains a collection of the named capturing groups you specified in matchAll()'s RegExp argument. Or undefined if the regular expression does not contain any named capturing group.

Let's now see another example of the matchAll() method.

Use matchAll() to match a pattern containing three capturing groups

// Assign a string to a variable:
const string = "It's a sunny Sunday!";

// Assign a regular expression to a variable:
const regExp = /(su)n(d(a)y)?/gi;

// Match the regular expression's pattern against the string and assign the result to a variable:
const iteratorResult = string.matchAll(regExp);

// Convert the iterator object to an array:
const arrayResult = [...iteratorResult];

// Print the arrayResult variable's content on the console:
console.log(arrayResult);

// The invocation above will return:
[
  ['sun', 'su', undefined, undefined, index: 7, input: "It's a sunny Sunday!", groups: undefined]
  ['Sunday', 'Su', 'day', 'a', index: 13, input: "It's a sunny Sunday!", groups: undefined]
]

In the returned arrays above,

• 'sun' and 'Sunday' refers to the matched pattern.
• 'su', 'Su', 'day', and 'a' indicates the matched capturing group patterns.
• index refers to the index position where the matched pattern began.
• input indicates the string on which you invoked matchAll().
• groups contains a collection of the named capturing groups you specified in matchAll()'s RegExp argument. Or undefined if the regular expression does not have any named capturing group.
• The two undefined values before index: 7 indicate that the second and third capturing groups are not defined in the first matched pattern: 'sun'.

CodeSweetly ads

Turn your passion into a business

Launch a digital products store with Shopify free trial.

Sign up now

Let's now see another example of the matchAll() method.

Use matchAll() to match a pattern containing a named capturing group

// Assign a string to a variable:
const string = "Tuesday";

// Assign a regular expression to a variable:
const regExp = /d(?<bestLetter>a)y/g;

// Match the regular expression's pattern against the string and assign the result to a variable:
const iteratorResult = string.matchAll(regExp);

// Convert the iterator object to an array:
const arrayResult = [...iteratorResult];

// Print the arrayResult variable's content on the console:
console.log(arrayResult);

// The invocation above will return:
[['day', 'a', index: 4, input: 'Tuesday', groups: {bestLetter: 'a'}]]

In the returned array above,

• 'day' refers to the matched pattern.
• 'a' indicates the matched capturing group pattern.
• index refers to the index position where the matched pattern began.
• input indicates the string on which you invoked matchAll().
• groups contains a collection of the named capturing groups you specified in matchAll()'s RegExp argument. Or undefined if the regular expression does not contain any named capturing group.

Let's now see another example of the matchAll() method.

Use matchAll() to match a pattern containing two named capturing groups

// Assign a string to a variable:
const string = "It's a sunny Sunday!";

// Assign a regular expression to a variable:
const regExp = /(?<groupOf2>su)nd(?<bestLetter>a)y/gi;

// Match the regular expression's pattern against the string and assign the result to a variable:
const iteratorResult = string.matchAll(regExp);

// Convert the iterator object to an array:
const arrayResult = [...iteratorResult];

// Print the arrayResult variable's content on the console:
console.log(arrayResult);

// The invocation above will return:
[['Sunday', 'Su', 'a', index: 13, input: "It's a sunny Sunday!", groups: {groupOf2: 'Su', bestLetter: 'a'}]]

In the returned array above,

• 'Sunday' refers to the matched pattern.
• 'Su' indicates the first matched capturing group pattern.
• 'a' indicates the second matched capturing group pattern.
• index refers to the index position where the matched pattern began.
• input indicates the string on which you invoked matchAll().
• groups contains a collection of the named capturing groups you specified in matchAll()'s RegExp argument. Or undefined if the regular expression does not contain any named capturing group.

Now, let's discuss the differences between matchAll() and match().

matchAll() vs. match() – What's the Difference?

The three main differences between matchAll() and match() are these:

1. Returned value

matchAll() returns an iterator while match() returns an array.

Here's an example:

"Tuesday".matchAll(/day/g); // RegExp String Iterator {  }

"Tuesday".match(/day/g); // ['day']

2. Global flag

matchAll() does not work without a global flag.

"Tuesday".matchAll(/day/);

// The invocation above will return: "Uncaught TypeError"

However, match() works irrespective of the presence or absence of a global flag.

Here's an example:

"Tuesday".match(/day/);

// The invocation above will return:
['day', index: 4, input: 'Tuesday', groups: undefined]

CodeSweetly ads

Create NPM Package like a pro

Learn the fundamentals of building and managing NPM packages from scratch.

Find out more

3. Capturing group

matchAll() works better with capturing groups than the match() method.

For instance, if you use a global flag (g) with match()'s RegExp argument, the computer will ignore the regular expression's capture groups.

Example

const string = "SunDay, Tuesday, and Friday are good DAYS";
const regExp = /(\w+)d(a)y/g;
const result = string.match(regExp);

console.log(result);

// The invocation above will return:
["Tuesday", "Friday"];

However, matchAll() allows easy access to capture groups.

Here's an example:

const string = "SunDay, Tuesday, and Friday are good DAYS";
const regExp = /(\w+)d(a)y/g;
const result = [...string.matchAll(regExp)];

console.log(result);

// The invocation above will return:
[
  ['Tuesday', 'Tues', 'a', index: 8, input: 'SunDay, Tuesday, and Friday are good DAYS', groups: undefined],
  ['Friday', 'Fri', 'a', index: 21, input: 'SunDay, Tuesday, and Friday are good DAYS', groups: undefined]
]

Overview

matchAll() creates a new iterator object containing all the patterns—including capturing groups—that match the method's regular expression argument.

Your support matters: Buy me a coffee to support CodeSweetly's mission of simplifying coding concepts.

Tweet this article