JavaScript match() Method String.match() Method (Regular Expressions)

This tutorial covers the match() method, part of JavaScript's String object. The match() method is applied on a string variable or literal, and takes a regular expression pattern as argument. If matches were found in the string, the match() method returns an array containing all matched substrings. JavaScript match() method's syntax While the match() method belongs to the String object, we felt it best to cover it in our regular expression tutorials, (along with the String search() and replace() methods), since these mostly rely on the power of regular expressions.

Compare the String object's match() method with the similar RegExp object's exec() method.

Using the match() Method

JavaScript's match() method is applied either on a string variable or literal string, and takes as argument the regular expression pattern you want to match. The JavaScript code below attempts to extract a copy of all substring matching a number. Notice that we pass a regular expression literal to the match() method; if you feel more comfortable, you can also declare a new regular expression pattern, store it in a variable, and then pass it to the match() method - both approaches achieve the same effect, but the latter is a bit more user-friendly.

var carter = "On April 4th, 1856, 53 soldiers were killed.";

// Use the match() method to create an array
var arlene = carter.match(/\d/g);

// Use the join() method to display one match per line
alert( arlene.join("\n") );

Our script extracted all numbers it was able to match in the string; the regular expression pattern we defined only matched a number at a time (as opposed to matching groups of numbers), which explains that each element in the array returned by the match() method contained a single digit: JavaScript match() method

This approach was fine, since we knew that we'd get at least a few matches. In a real world situation, however, an unmatched pattern in the script above would throw an unfriendly error message (since the match() function would have returned null instead of an array of matches).

The match() Method and Unmatched Regular Expression Patterns

The match() method returns an array containing all substrings matching the regular expression pattern passed as argument. If no match was successful, no array was returned: therefore, the match() method returns null if it could not match the pattern. You should prepare your scripts this eventuality.

var carter = "On April 4th, 1856, 53 soldiers were killed.";

var arlene = carter.match(/javascript/gi);

// Ensure that the match() method found at least one match
if( arlene!=null )
    alert( arlene.join("\n") );
    alert("No match was found!");

In the above script, the match() method was not able to extract matching substrings, and thus returned null; this time, our script was ready to handle an unsuccessful matching attempt. JavaScript match() method unsuccessful in matching a regular expression pattern

Remember to handle possible null return values by the match() method.

Test the match() Method

Interactively test the match() method by editing the JavaScript code below and clicking the Test match() Method button.

Browser support for JavaScript match() method
Internet Explorer supports the JavaScript match() methodFirefox supports the JavaScript match() methodSafari supports the JavaScript match() methodOpera supports the JavaScript match() method