String.prototype.match()

The match() method retrieves the result of matching a string against a regular expression.

Syntax

str.match(regexp)

Parameters

regexp
A regular expression object.
If regexp is a non-RegExp object, 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: [""].

Return value

An Array whose contents depend on the presence or absence of the global (g) flag, or 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 will not.
  • if the g flag is not used, only the first complete match and its related capturing groups are returned. In this case, the returned item will have additional properties as described below.

Additional properties

As explained above, some results contain additional properties as described below.

groups
An array of named capturing groups or undefined if no named capturing groups were defined. See Groups and Ranges for more information.
index
The index of the search at which the result was found.
input 
A copy of the search string.

Description

If the regular expression does not include the g flag, str.match() will return the same result as RegExp.exec()

Other methods

Examples

Using match()

In the following example, match() is used to find 'Chapter' followed by 1 or more numeric characters followed by a decimal point and numeric character 0 or more times.

The regular expression includes the i flag so that upper/lower case differences will be ignored.

let str = 'For more information, see Chapter 3.4.5.1';
let re = /see (chapter \d+(\.\d)*)/i;
let found = str.match(re);

console.log(found);

// logs [ 'see Chapter 3.4.5.1',
//        'Chapter 3.4.5.1',
//        '.1',
//        index: 22,
//        input: 'For more information, see Chapter 3.4.5.1' ]

// 'see Chapter 3.4.5.1' is the whole match.
// 'Chapter 3.4.5.1' was captured by '(chapter \d+(\.\d)*)'.
// '.1' was the last value captured by '(\.\d)'.
// The 'index' property (22) is the zero-based index of the whole match.
// The 'input' property is the original string that was parsed.

Using global and ignore case flags with match()

The following example demonstrates the use of the global and ignore case flags with match(). All letters A through E and a through e are returned, each its own element in the array.

let str = 'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz';
let regexp = /[A-E]/gi;
let matches_array = str.match(regexp);

console.log(matches_array);
// ['A', 'B', 'C', 'D', 'E', 'a', 'b', 'c', 'd', 'e']

Using named capturing groups

In browsers which support named capturing groups, the following code captures "fox" or "cat" into a group named "animal":

let paragraph = 'The quick brown fox jumps over the lazy dog. It barked.';

let capturingRegex = /(?<animal>fox|cat) jumps over/;
found = paragraph.match(capturingRegex);
console.log(found.groups); // {animal: "fox"}

Using match() with no parameter

let str = "Nothing will come of nothing.";

str.match();   // returns [""]

A non-RegExp object as the parameter

When the regexp parameter is a string or a number, it is implicitly converted to a RegExp by using new RegExp(regexp).

If it is a positive number with a positive sign, RegExp() will ignore the positive sign. 

let str1 = "NaN means not a number. Infinity contains -Infinity and +Infinity in JavaScript.",
    str2 = "My grandfather is 65 years old and My grandmother is 63 years old.",
    str3 = "The contract was declared null and void.";
str1.match("number");   // "number" is a string. returns ["number"]
str1.match(NaN);        // the type of NaN is the number. returns ["NaN"]
str1.match(Infinity);   // the type of Infinity is the number. returns ["Infinity"]
str1.match(+Infinity);  // returns ["Infinity"]
str1.match(-Infinity);  // returns ["-Infinity"]
str2.match(65);         // returns ["65"]
str2.match(+65);        // A number with a positive sign. returns ["65"]
str3.match(null);       // returns ["null"]

Specifications

Specification
ECMAScript Latest Draft (ECMA-262)
The definition of 'String.prototype.match' in that specification.

Browser compatibility

Basic support for match()

Update compatibility data on GitHub
DesktopMobileServer
ChromeEdgeFirefoxInternet ExplorerOperaSafariAndroid webviewChrome for AndroidFirefox for AndroidOpera for AndroidSafari on iOSSamsung InternetNode.js
matchChrome Full support 1Edge Full support 12Firefox Full support 1IE Full support 4Opera Full support YesSafari Full support 1WebView Android Full support 1Chrome Android Full support 18Firefox Android Full support 4Opera Android Full support YesSafari iOS Full support 1Samsung Internet Android Full support 1.0nodejs Full support Yes
flags
DeprecatedNon-standard
Chrome No support NoEdge No support NoFirefox No support 1 — 49IE No support NoOpera No support NoSafari No support NoWebView Android No support NoChrome Android No support NoFirefox Android No support 4 — 49Opera Android No support NoSafari iOS No support NoSamsung Internet Android No support Nonodejs No support No

Legend

Full support  
Full support
No support  
No support
Non-standard. Expect poor cross-browser support.
Non-standard. Expect poor cross-browser support.
Deprecated. Not for use in new websites.
Deprecated. Not for use in new websites.

Support for named capture groups

Update compatibility data on GitHub
DesktopMobileServer
ChromeEdgeFirefoxInternet ExplorerOperaSafariAndroid webviewChrome for AndroidFirefox for AndroidOpera for AndroidSafari on iOSSamsung InternetNode.js
Named capture groupsChrome Full support 64Edge No support NoFirefox No support NoIE No support NoOpera Full support 51Safari Full support 11.1WebView Android Full support 64Chrome Android Full support 64Firefox Android No support NoOpera Android Full support 47Safari iOS Full support 11.3Samsung Internet Android Full support 9.0nodejs Full support 10.0.0
Full support 10.0.0
Full support 8.3.0
Disabled
Disabled From version 8.3.0: this feature is behind the --harmony runtime flag.

Legend

Full support  
Full support
No support  
No support
User must explicitly enable this feature.
User must explicitly enable this feature.

Firefox-specific notes

  • flags was a non-standard second argument only available in Firefox: str.match(regexp, flags). It has been removed starting with Firefox 49.
  • Firefox 27 this method has been adjusted to conform with the ECMAScript specification. When match() is called with a global regular expression, the RegExp.lastIndex property (if specified) will be reset to 0 (bug 501739).

See also