graphemer

library1.4.0jsnpmunverified

Graphemer is a JavaScript and TypeScript library designed to accurately split strings into user-perceived characters, also known as 'extended grapheme clusters' in Unicode terminology. It addresses the complexities of Unicode, where a single visual character can be composed of multiple JavaScript characters (e.g., emojis, combining marks), which standard string operations often fail to handle correctly. The library is currently stable at version 1.4.0, which supports Unicode 15 and below. It follows a release cadence tied to new Unicode versions, typically updating annually. Key differentiators include its adherence to UAX #29's Default Grapheme Cluster Boundary rules, providing a robust solution for internationalization (i18n) and accurate character counting that standard JavaScript methods like `String.prototype.length` or simple `String.prototype.split('')` cannot achieve, especially with complex scripts and emoji sequences.

serialization data

npm install graphemer

github ↗package ↗

INSTALL

IMPORT

SIG · GRAPHEMER

graphemer

serializationjavascriptv1.4.0

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

Graphemer

✓ import Graphemer from 'graphemer';

✗ import { Graphemer } from 'graphemer';

Graphemer is exported as a default export in ESM. Attempting a named import will result in an error.

Graphemer (CommonJS)

✓ const Graphemer = require('graphemer').default;

✗ const Graphemer = require('graphemer');

When using CommonJS `require`, the `default` property must be accessed to get the Graphemer class, as it's an ESM default export transpiled for CJS.

Demonstrates initializing Graphemer and using `splitGraphemes`, `iterateGraphemes`, and `countGraphemes` with complex Unicode strings including emojis, combining marks, and Zalgo text.

import Graphemer from 'graphemer'; const splitter = new Graphemer(); const emojiString = 'Hello 🏳️‍🌈 world! 👋🏽'; const hindiString = 'अनुच्छेद'; // 5 user-perceived letters const zalgoString = 'Z͑ͫ̓ͪ̂ͫ̽͏̴̙̤̞͉͚̯̞̠͍A̴̵̜̰͔ͫ͗͢L̠ͨͧͩ͘G̴̻͈͍͔̹̑͗̎̅͛́Ǫ̵̹̻̝̳͂̌̌͘'; console.log('Original emoji string length:', emojiString.length); // 19 const emojiGraphemes = splitter.splitGraphemes(emojiString); console.log('Split emoji graphemes:', emojiGraphemes); // ['H', 'e', 'l', 'l', 'o', ' ', '🏳️‍🌈', ' ', 'w', 'o', 'r', 'l', 'd', '!', ' ', '👋🏽'] console.log('Emoji grapheme count:', emojiGraphemes.length); // 16 const hindiGraphemes = splitter.splitGraphemes(hindiString); console.log('Hindi grapheme count:', hindiGraphemes.length); // 5 const zalgoGraphemes = splitter.splitGraphemes(zalgoString); console.log('Zalgo grapheme count:', zalgoGraphemes.length); // 5 // Iterate through graphemes for (const grapheme of splitter.iterateGraphemes(emojiString)) { console.log('Iterated grapheme:', grapheme); } // Get count directly const count = splitter.countGraphemes(emojiString); console.log('Direct grapheme count:', count);

Debug

Known issues

breakingOlder versions of `graphemer` may not correctly parse strings containing newer Unicode versions due to the underlying Grapheme Cluster Boundary Algorithm updates. Each major/minor release often updates Unicode support.

fix

Upgrade to the latest version of `graphemer` to ensure support for the most recent Unicode specification. For example, v1.0.0 supports Unicode 11, v1.1.0 supports Unicode 13, and v1.4.0 supports Unicode 15.

affects: <1.4.0

gotchaMixing CommonJS `require` with an ESM default export requires accessing the `.default` property. Forgetting this will result in `Graphemer` being an object containing the class, not the class constructor itself, leading to 'TypeError: Graphemer is not a constructor'.

fix

When using CommonJS, import `Graphemer` as `const Graphemer = require('graphemer').default;`.

affects: >=1.0.0

Errors

Common errors & fixes

TypeError: Graphemer is not a constructor

Attempting to instantiate `Graphemer` from a CommonJS `require` call without accessing the `.default` property.

fix

Change `const Graphemer = require('graphemer');` to `const Graphemer = require('graphemer').default;`.

SyntaxError: Named export 'Graphemer' not found. The requested module 'graphemer' does not provide an export named 'Graphemer'

Attempting to use a named import for `Graphemer` when it is a default export in ESM.

fix

Change `import { Graphemer } from 'graphemer';` to `import Graphemer from 'graphemer';`.

Upgrade

Version history

1.4.0latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

11 hits · last 30 days

node

Resources

githubhttps://github.com/flmnt/graphemer ↗

packagehttps://www.npmjs.com/package/graphemer ↗