emoji-regex: a Unicode-derived pattern for matching emoji sequences

The pattern is generated from the Unicode test data

The package offers a regular expression that matches emoji symbols and sequences, including the textual representations of emoji, as defined by the Unicode Standard. The important detail is where the pattern comes from. It is based on the emoji-test-regex-pattern project, which generates the regular expression pattern at build time from the Unicode Standard itself, and that is why the package can be updated whenever new emoji are added to Unicode without anyone hand editing a character class. The repository is thin by design. The published files are a licence file, a type declaration and one module, and the build lives in a script directory with the source and tests alongside. What you install is small; what it knows is not.

Determinism is the reason the pattern is this big

Each release of emoji-regex is tied to the latest Unicode version at the time of release, and the documentation explains why that matters with a concrete case. For use cases like image replacement, you want the guarantee that an image asset is available for every emoji the pattern can possibly match. A pattern that silently gains new matches when Unicode moves forward would break that guarantee, so the package pins its results instead. If you do not need a deterministic regex, the documentation points at a lighter-weight, general emoji pattern published as emoji-regex-xs, which follows the same API. The difference is exactly the trade you would expect: one gives you a stable, complete set of matches, the other gives you a smaller pattern that moves with the standard.

The package exports a factory, not the regex itself

The import looks like importing any other module, but the shape of the export is deliberate. Because the regular expression has the global flag set, the module exports a function that returns the regex rather than exporting the regular expression itself, and the documentation says the reason is to make it impossible to accidentally mutate the original regular expression. A global regex carries state in its lastIndex property, so a shared instance used with a loop and a reset can produce surprises. Handing out a fresh instance per call removes that class of bug.

import emojiRegex from 'emoji-regex';

const regex = emojiRegex();
for (const match of text.matchAll(regex)) {

The package ships TypeScript declarations alongside the module, and the manifest points its main entry at the ES module file with the declaration file as its types entry.

Matches are sequences, and the code point count shows it

The worked example in the documentation feeds a small block of text to the pattern and prints each match with its number of code points. The results are what make the point about sequences. A watch is one code point, but the left-right arrow with its variation selector is two, because the selector is what asks for the emoji presentation rather than the default text one. The base of a modifier sequence, the woman figure, matches on its own as one code point, and the same figure followed by a skin tone modifier matches as a single two code point sequence. That is the behaviour you want for replacement logic, because replacing the modifier sequence as a unit is the only way the result still renders.

Updating after a Unicode release is a four step routine

The maintainer instructions describe the full loop, and it is worth reading even if you never maintain the package, because it shows what the version numbers mean. First, the upstream emoji-test-regex-pattern project is updated following its own instructions. Then that dependency is bumped to the latest version. Then the Unicode data dependency in the manifest is replaced, for example moving from the Unicode 13 package to the Unicode 14 one.

# Example: updating from Unicode v13 to Unicode v14.
npm uninstall @unicode/unicode-13.0.0
npm install @unicode/unicode-14.0.0 --save-dev

The new output is generated with the build script and the tests are run to confirm nothing broke.

npm run build

npm test

Publishing then means bumping the version in the manifest, with patch, minor or major as needed, which produces a commit and a tag, and pushing both the commit and the tags. The CI pipeline publishes to npm automatically after that.

Versions are npm versions, with no GitHub releases

The manifest records version 11.0.0, with the build script running a file in the script directory and the tests run through the Node test runner rather than a framework. The development dependencies show exactly what the pattern is built from, a specific Unicode data package and the emoji-test-regex-pattern generator, plus a formatter. The repository itself has no GitHub releases at all, because the package is distributed through npm, and the CI workflow publishes there. The last push to the repository was on 2026-09-15, the project is not archived, and the licence is MIT, which requires keeping the copyright notice when you redistribute it.

Editorial conclusion

Use emoji-regex when the set of characters you match has to be pinned, for example when a build step replaces every emoji with an asset and you need to know that an asset exists for each match. Use the lighter alternative instead when you only need to recognise emoji roughly and care more about bundle size, since it follows the same API without the determinism guarantee. Before you upgrade, note that the package version tracks the Unicode version it was built from, so a new release can add matches that your asset pipeline has never seen, and check your replacement table against the new pattern.

Frequently asked questions

Official sources

1. Issues
2. License: MIT
3. mathiasbynens/emoji-regex on GitHub
4. Project website
5. README