Definition and Usage

The match() function for strings uses a regular expression to find parts of a given string that match and returns the result.

Features

  • This function is case-sensitive.
  • If a match is found, it returns an array containing the matched parts.
  • If no match is found, it returns null.
  • It is useful for checking strings against specific patterns, such as email addresses, URLs, and HTML tags.

Basic Example

JavaScript 
const str = "apple orange banana apple";

/* Finds only the first matching pattern in the string
   and returns the result as an array.
   (The first element of the returned array is the matched string,
   and the following properties include index, input, and groups.) */
const pattern = /apple/;
const result = str.match(pattern);

console.log(result); // Output: ["apple", index: 0, input: "apple orange banana apple", groups: undefined]
console.log(result.length); // Output: 1
console.log(result[0]);     // Output: "apple"

/* If you want to find all matching pattern strings
   throughout the entire text,
   add the g (global search) flag to the regular expression.
   When the g flag is used, the index, input, and groups properties
   are not included in the returned array.
   Instead, each matching string is returned as a separate array element. */
const globalPattern = /apple/g;
const globalResult = str.match(globalPattern);

console.log(globalResult);        // Output: ["apple", "apple"]
console.log(globalResult.length); // Output: 2
console.log(globalResult[0]);     // Output: "apple"
console.log(globalResult[1]);     // Output: "apple"

/* Checking strings against a specific pattern
   Searching for an email address pattern */
const userInfo = "My email address is user@example.com.";
const searchEmailPattern = /\w+@\w+\.\w+/g;
const searchEmailResult = userInfo.match(searchEmailPattern);

console.log(searchEmailResult);        // Output: ["user@example.com"]
console.log(searchEmailResult.length); // Output: 1
console.log(searchEmailResult[0]);     // Output: "user@example.com"

Syntax

JavaScript 
str.match(regexp);

str is the string to which the match() function is applied.

Parameters

Parameters of the string match() function
regexp
  • A regular expression object.
  • If regexp is a string or a number, it is automatically converted into a regular expression object internally using new RegExp(regexp).

Return value

  • If a match is found, an array containing the matched result is returned. The structure of the returned array differs depending on whether the g (global) flag is used in the regular expression.
    • g flag not used: The first element of the array is the matched pattern string, followed by additional detail properties (index, input, and groups).
    • g flag used: An array is returned in which all matched pattern strings are included as individual elements. No additional detail properties are included.
  • If no match is found, null is returned.
The following is a brief supplementary explanation of the "g flag" term.
g flag
In regular expressions, the g flag is used to indicate a global search.
In JavaScript, a regular expression is written by enclosing a pattern between slashes (/). When the g character is appended to the closing slash, it specifies that the regular expression should perform a global search. For this reason, it is commonly referred to as the "g flag."
When the g flag is used with the match() function, all matching substrings found in the entire string are returned as individual elements in an array.

g Flag and Return Value Examples

This section examines how the structure of the returned array differs depending on whether the g (global) flag is used in the regular expression passed as a parameter.

g Flag Not Used

When the g flag is not used, the first element of the returned array is the matched substring. The remaining elements are detail properties (index, input, and groups). If no match is found, null is returned.

Although multiple items appear when the array is logged, it is important to note that the actual length of the array (length) is 1.

JavaScript 
const str = "apple orange banana apple";
const pattern = /apple/; // without the g flag
const result = str.match(pattern);

console.log(result);
// Output: ["apple", index: 0, input: "apple orange banana apple", groups: undefined]

console.log(result.length); // Output: 1
g Flag Used

When the g flag is used, all matching substrings are returned as individual elements in an array. In this case, detail properties (index, input, and groups) are not included in the array. If no match is found, null is returned.

Here, the length of the returned array reflects the actual number of matched elements.

JavaScript 
const str = "apple orange banana apple";
const globalPattern = /apple/g; // with the g flag
const globalResult = str.match(globalPattern);

console.log(globalResult); // Output: ["apple", "apple"]
console.log(globalResult.length); // Output: 2

When No Argument Is Provided

f the match() function is called without any arguments, it returns an array containing an empty string ("").

JavaScript 
const str = "Hello, World!";
const result = str.match();

console.log(result); 
// Output: ["", index: 0, input: "Hello, World!", groups: undefined]

console.log(result.length); // Output: 1

Additional Explanation
In an array, the length property returns the number of elements contained in the array as a numeric value.

When the Argument Is an Empty String ("")

If the argument is an empty string (""), the function returns an array containing an empty string.

JavaScript 
const str = "Hello, World!";
const result = str.match("");

console.log(result); 
// Output: ["", index: 0, input: "Hello, World!", groups: undefined]

console.log(result.length); // Output: 1

When the Argument Is a Whitespace String (" ")

If the argument is a whitespace string (" "), that string is treated as the pattern. The function searches the string for matching whitespace characters and returns an array containing the matched whitespace.

JavaScript 
const str = "Hello, World!";
const result = str.match(" ");

console.log(result); 
// Output: [" ", index: 6, input: "Hello, World!", groups: undefined]

console.log(result.length); // Output: 1

When Multiple Matches Exist for the Given Pattern

If multiple substrings match the given pattern, only the first matching substring is returned as an array when the g flag is not used.

JavaScript 
const str = "apple orange banana apple";
const pattern = /apple/;

const result = str.match(pattern);
console.log(result); 
// Output: ["apple", index: 0, input: "apple orange banana apple", groups: undefined]

console.log(result.length); // Output: 1

Returning All Matching Substrings

If you want to find all matching substrings in the entire text, add the g (global search) flag to the regular expression.

JavaScript 
const str = "apple orange banana apple";
const pattern = /apple/g; // <= add the g (global search) flag
const result = str.match(pattern);

console.log(result); // Output: ["apple", "apple"]
console.log(result[0]);
console.log(result[1]);
console.log(result.length); // Output: 2

Regular expression flags are written in the form /regex/flags, where regex represents the pattern and flags specify the options. In the example above, /apple/g means that the g (global search) flag is added to the regular expression /apple/.

Finding Strings Without Case Sensitivity

Regular expressions are case-sensitive by default. However, using the i (case-insensitive search) flag allows you to find matching substrings without distinguishing between uppercase and lowercase letters.

JavaScript 
const str = "Apple orange banana Apple";

// without the g flag / with the i flag
const pattern1 = /apple/i;
const result1 = str.match(pattern1);
console.log(result1); 
// Output: ["Apple", index: 0, input: "Apple orange banana Apple", groups: undefined]

// with the g flag / with the i flag
const pattern2 = /apple/gi; // exactly the same as /apple/gi (flag order does not matter)
const result2 = str.match(pattern2);
console.log(result2); // Output: ["Apple", "Apple"]

When No Matching Substring Is Found

If no matching pattern is found, null is returned.

JavaScript 
const str = "Hi, World!";
const pattern = /Hello/;
const result = str.match(pattern);

console.log(result); // Output: null

Practical Examples

The match() function is useful for validating strings that follow specific patterns, such as email addresses, URLs, and HTML tags. It can also be applied effectively in a wide range of practical scenarios. Below are several representative examples.

Email Address Validation

JavaScript 
const text = "For inquiries, please contact help@example.com or support@example.org.";

const emailPattern =
    /\b[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\.[A-Za-z]{2,}\b/g;
const emailMatches = text.match(emailPattern);

console.log(emailMatches);
// Output: ["help@example.com", "support@example.org"]

URL Validation

JavaScript 
const text = "For more information, visit https://www.example.com.";

const urlPattern =
    /\b(?:https?:\/\/)?(?:www\.)?[a-zA-Z0-9-]+(?:\.[a-z]{2,})+(?:\/[^\s]*)?\b/g;
const urlMatches = text.match(urlPattern);

console.log(urlMatches);
// Output: ["https://www.example.com"]

Extracting Tags from HTML

JavaScript 
const html = '<div class="container"><p>Hello, <b>world!</b></p></div>';
const tagPattern = /<[^>]+>/g;
const tags = html.match(tagPattern);

console.log(tags);
// Output: ["<div class=\"container\">", "<p>", "<b>", "</b>", "</p>", "</div>"]

Extracting CSS Class Selectors

JavaScript 
const css = ".header { color: #333; } .main-content { font-size: 16px; }";
const classPattern = /\.([a-zA-Z_\d-]+)/g;
const classes = css.match(classPattern);

console.log(classes);
// Output: [".header", ".main-content"]

Compatibility

Compatibility for JavaScript String match() Function
Method
Desktop Chrome
Chrome
DesktopDesktop Edge
Edge
Desktop Firefox
Firefox
Safari
Safari
Node.js
Node.js
match() 1 12 1 1 0.10

Specifications

Specification for JavaScript String match() Function
Specification
match() ECMAScript® 2026 Language Specification
#sec-string.prototype.match

References

See also