String.prototype.match()

Baseline Widely available

This feature is well established and works across many devices and browser versions. It’s been available across browsers since July 2015.

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

Try it

const paragraph = "The quick brown fox jumps over the lazy dog. It barked.";
const regex = /[A-Z]/g;
const found = paragraph.match(regex);

console.log(found);
// Expected output: Array ["T", "I"]

Syntax

match(regexp)

Parameters

regexp

A regular expression object, or any object that has a Symbol.match 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 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).

The implementation of String.prototype.match doesn't do much other than calling the Symbol.match method of the argument with the string as the first parameter. The actual implementation comes from RegExp.prototype[Symbol.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() instead.

For more information about the semantics of match() when a regex is passed, see RegExp.prototype[Symbol.match]().

Examples

Using match()

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

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

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

console.log(found);
// [
//   'see Chapter 3.4.5.1',
//   'Chapter 3.4.5.1',
//   '.1',
//   index: 22,
//   input: 'For more information, see Chapter 3.4.5.1',
//   groups: undefined
// ]

In the match result above, '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 ignoreCase flags with match()

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

js
const str = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz";
const regexp = /[a-e]/gi;
const matches = str.match(regexp);

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

Note: See also String.prototype.matchAll() and Advanced searching with flags.

Using named capturing groups

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

js
const paragraph = "The quick brown fox jumps over the lazy dog. It barked.";

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

Using match() with no parameter

js
const str = "Nothing will come of nothing.";

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

Using match() with a non-RegExp implementing [Symbol.match]()

If an object has a Symbol.match method, it can be used as a custom matcher. The return value of Symbol.match becomes the return value of match().

js
const str = "Hmm, this is interesting.";

str.match({
  [Symbol.match](str) {
    return ["Yes, it's interesting."];
  },
}); // returns ["Yes, it's interesting."]

A non-RegExp 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).

js
const str1 =
  "All numbers except NaN satisfy <= Infinity and >= -Infinity in JavaScript.";
const str2 =
  "My grandfather is 65 years old and My grandmother is 63 years old.";
const 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"]
str2.match(65); // returns ["65"]
str3.match(null); // returns ["null"]

This may have unexpected results if special characters are not properly escaped.

console.log("123".match("1.3")); // [ "123" ]

This is a match because . in a regex matches any character. In order to make it only match specifically a dot character, you need to escape the input.

console.log("123".match("1\\.3")); // null