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

The **`match()`** method retrieves the result of matching a string against a [regular expression](https://developer.mozilla.org/docs/Web/JavaScript/Guide/Regular_Expressions).

## Syntax

```js
match(regexp)
```

### Parameters

- `regexp`

  - : A regular expression object, or any object that has a [`Symbol.match`](../../../globals/Symbol/match.mdx) method.

    If `regexp` is not a `RegExp` object and does not have a `Symbol.match` method, it is implicitly converted to a `RegExp` by using `new RegExp(regexp)`.

    If you don't give any parameter and use the `match()` method directly, you will get an `Array` with an empty string: `[""]`, because this is equivalent to `match(/(?:)/)`.

### Return value

An `Array` whose contents depend on the presence or absence of the global (`g`) flag, or [`null`](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Operators/null) if no matches are found.

- If the `g` flag is used, all results matching the complete regular expression will be returned, but capturing groups are not included.
- If the `g` flag is not used, only the first complete match and its related capturing groups are returned. In this case, `match()` will return the same result as `RegExp.prototype.exec()` (an array with some extra properties).

## Description

The implementation of `String.prototype.match` itself is very simple — it simply calls the `Symbol.match` method of the argument with the string as the first parameter. The actual implementation comes from [`RegExp.prototype[@@match]()`](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/RegExp/@@match).

- If you need to know if a string matches a regular expression `RegExp`, use `RegExp.prototype.test()`.
- If you only want the first match found, you might want to use `RegExp.prototype.exec()` instead.
- If you want to obtain capture groups and the global flag is set, you need to use `RegExp.prototype.exec()` or [`String.prototype.matchAll()`](../../../globals/String/prototype/matchAll.mdx) instead.

For more information about the semantics of `match()` when a regex is passed, see [`RegExp.prototype[@@match]()`](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/RegExp/@@match).
