JavaScript RegExp

RegExp exec, test, lastIndex with the g and y flags, UTF-16 versus the u flag, and matchAll requiring a global regex.

RegExp is an ECMAScript built-in. It is not a DOM API. The String page already shows replace, replaceAll, and split; this page covers the RegExp object itself, especially lastIndex and Unicode.

JavaScript strings are UTF-16. A code point outside the BMP, such as an emoji, uses two code units. A pattern without the u flag treats those units separately, so a single "." does not match the whole character. With u, "." matches one code point.

Examples were checked in Node.js 22, which implements these ECMAScript built-ins. See the MDN documentation for the complete API.

JavaScript tutorial and API overview →

API index

APISummary
RegExp.prototype.exec, RegExp.prototype.test, lastIndexSearch a string with exec or test. With the g or y flag, lastIndex is the start position and is updated after each call.
RegExp u flag, String.prototype.matchAllUse the u flag when a pattern should see Unicode code points rather than UTF-16 code units. matchAll requires the g flag.

exec, test, and lastIndex

exec searches for one match and returns an array or null. test returns a boolean. When the regex has the g (global) or y (sticky) flag, both methods start at lastIndex and then update it. After a successful global or sticky search, lastIndex is the index after the match. After a failure, lastIndex is reset to 0. A regex without g or y does not use lastIndex this way; test can be called again on the same string and still return true.

A common mistake is to call test in a loop with a /g regex. The second call starts after the first match and can return false even though the string still contains the pattern. Sticky /y only matches at lastIndex, not later in the string.

RegExp.prototype.exec, RegExp.prototype.test, lastIndex

regexp.exec(str)
regexp.test(str)
regexp.lastIndex

Search a string with exec or test. With the g or y flag, lastIndex is the start position and is updated after each call.

ParameterDescription
strThe string to search. exec and test convert the argument to a string.

Returns: exec returns a match array or null. test returns true or false. lastIndex is a number on the regex object.

  • In the /a/g example on "abaca", lastIndex moves 1, 3, 5, then a failed exec resets it to 0.
  • /foo/g on "foo" returns true with lastIndex 3, then false with lastIndex 0, then true again. Without g, both test calls return true and lastIndex stays 0.
  • If lastIndex is 1, /a/y matches the "a" in "ba" but does not match "ab", because sticky matching cannot skip the character at lastIndex.
javascript
const re = /a/g;
console.log(JSON.stringify(re.exec("abaca")), re.lastIndex);
console.log(JSON.stringify(re.exec("abaca")), re.lastIndex);
console.log(JSON.stringify(re.exec("abaca")), re.lastIndex);
console.log(JSON.stringify(re.exec("abaca")), re.lastIndex);

const t = /foo/g;
console.log(t.test("foo"), t.lastIndex);
console.log(t.test("foo"), t.lastIndex);
console.log(t.test("foo"), t.lastIndex);

const noG = /foo/;
console.log(noG.test("foo"), noG.lastIndex);
console.log(noG.test("foo"), noG.lastIndex);

const sticky = /a/y;
sticky.lastIndex = 1;
console.log(JSON.stringify(sticky.exec("ba")), sticky.lastIndex);
const miss = /a/y;
miss.lastIndex = 1;
console.log(JSON.stringify(miss.exec("ab")), miss.lastIndex);

Expected output

["a"] 1
["a"] 3
["a"] 5
null 0
true 3
false 0
true 3
true 0
true 0
["a"] 2
null 0

Related: String replace and replaceAll

MDN documentation →

UTF-16, the u flag, and matchAll

😀 is one code point and two UTF-16 code units, so its length is 2. /^.$/ without u fails because "." matches a single code unit. /^.$/u succeeds. A global /./g without u advances lastIndex by one code unit, which can leave the search in the middle of a surrogate pair.

String.prototype.matchAll returns an iterator of all matches and requires a global regex. If the pattern is missing the g flag, matchAll throws TypeError. The String page covers replaceAll, which has the same global-flag requirement.

RegExp u flag, String.prototype.matchAll

/pattern/u
/pattern/gu
string.matchAll(regexp)

Use the u flag when a pattern should see Unicode code points rather than UTF-16 code units. matchAll requires the g flag.

ParameterDescription
regexpFor matchAll, a regular expression that has the g flag. A regex without g throws TypeError.

Returns: test returns a boolean. exec returns a match or null and updates lastIndex. matchAll returns an iterator of match arrays, each with an index property.

Throws

  • TypeError — Thrown by matchAll when the regex is not global.
  • The emoji in the example is U+1F600. Its string length is 2. With the u flag, lastIndex after one exec is 2, not 1.
javascript
const emoji = "\u{1F600}";
console.log(emoji.length);
console.log(/^.$/.test(emoji), /^.$/u.test(emoji));
const units = /./g;
console.log(units.exec(emoji)[0].length, units.lastIndex);
const points = /./gu;
console.log(points.exec(emoji)[0], points.lastIndex);
try {
  "a".matchAll(/a/);
} catch (error) {
  console.log(error instanceof TypeError, error.name);
}
console.log(
  [..."abaca".matchAll(/a/g)].map((match) => [match[0], match.index]),
);

Expected output

2
false true
1 1
😀 2
true TypeError
[ [ 'a', 0 ], [ 'a', 2 ], [ 'a', 4 ] ]

Related: String UTF-16 length and code points

MDN documentation →