---
hide_title: false
hide_table_of_contents: false
pagination_next: null
pagination_prev: null
---
# String.prototype.matchAll()

The **`matchAll()`** method returns an iterator of all results matching a string against a [regular expression](https://developer.mozilla.org/docs/Web/JavaScript/Guide/Regular_Expressions), including [capturing groups](https://developer.mozilla.org/docs/Web/JavaScript/Guide/Regular_Expressions/Groups_and_Backreferences).

## Syntax

```js
matchAll(regexp)
```

### Parameters

- `regexp`

  - : A regular expression object, or any object that has a [`Symbol.matchAll`](../../../globals/Symbol/matchAll.mdx) 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](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/RegExp#special_handling_for_regexes), then it must have the global (`g`) flag set, or a [`TypeError`](../../../globals/TypeError/TypeError.mdx) is thrown.

### Return value

An [iterable iterator](https://developer.mozilla.org/docs/Web/JavaScript/Guide/Iterators_and_Generators) (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`](../../../globals/TypeError/TypeError.mdx)
  - : Thrown if the `regexp` [is a regex](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/RegExp#special_handling_for_regexes) that does not have the global (`g`) flag set (its [`flags`](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/RegExp/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]()`](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/RegExp/@@matchAll).
