JavaScriptStringsIntermediate

String.match()

Finds matches using a regex and returns match details (or null).

Review the syntaxStudy the examplesOpen the coding app
string.match(regexp)
Open Coding Reference

This static page keeps the syntax and examples indexed for search, while the coding app handles interactive exploration and saved references.

What it does

Overview

Finds matches using a regex and returns match details (or null).

The match() method retrieves the results of matching a string against a regular expression. Its behavior shifts significantly based on the presence of the global (g) flag. If the flag is absent, match() returns an array containing the full match followed by its capturing groups, along with additional properties like 'index' (where the match begins) and 'input'. If the 'g' flag is present, the method returns a simple array of all matching substrings, omitting capturing groups and metadata. A critical edge case is that if no match is found, match() returns null instead of an empty array. This often leads to runtime errors if the result is immediately accessed or iterated without a null check. For performance-sensitive code where you only need a boolean check for existence, RegExp.prototype.test() is preferred as it avoids the overhead of array allocation. If you pass a non-RegExp object, it is implicitly converted via new RegExp(obj).

Quick reference

Syntax

string.match(regexp)

Inputs

Parameters

regexpRegExp · Pattern to match against the string.

See it in practice

Examples

1

Basic Retrieval with Capturing Groups

var str = 'The rain in Spain stays mainly in the plain';
var regex = /([A-Z])\w+/;
var found = str.match(regex);

console.log(found[0]);
console.log(found[1]);
console.log(found.index);
Output:
"Spain" "S" 12

Without the global flag, the array contains the full match ('Spain'), the first capture group ('S'), and the index of occurrence.

2

Global Search for All Occurrences

var str = 'ABC123XYZ456';
var regex = /\d+/g;
var results = str.match(regex);

console.log(results);
Output:
["123", "456"]

When the global flag is used, all matches are collected into a flat array. Capturing groups and index properties are not included in this mode.

3

Handling No Matches Gracefully

var str = 'JavaScript';
var result = str.match(/Python/) || [];

console.log(result.length);
Output:
0

Since match() returns null when no pattern is found, using a logical OR with an empty array prevents 'Cannot read property length of null' errors.

Debug faster

Common Errors

1

TypeError

Cause: Attempting to access the result of match() when no matches are found without checking for null.

Fix: Use a null check or provide a default empty array fallback.

var count = 'abc'.match(/\d+/).length; // Throws TypeError if no digits
2

LogicError

Cause: Expecting capturing groups to be present in the returned array when the global (/g) flag is active.

Fix: Use String.prototype.matchAll() to retrieve global matches along with their respective capturing groups.

var matches = 'A1 B2'.match(/([A-Z])(\d)/g);
// matches is ['A1', 'B2']; group 'A' and '1' are lost.

Runtime support

Compatibility

Node.js, BrowserAll browsersES3+

Source: MDN Web Docs

Common questions

Frequently Asked Questions

Finds matches using a regex and returns match details (or null).

regexp: Pattern to match against the string.

TypeError: Use a null check or provide a default empty array fallback. LogicError: Use String.prototype.matchAll() to retrieve global matches along with their respective capturing groups.