{"id":10965,"library":"graphemer","title":"Graphemer: Unicode Character Splitter","description":"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.","status":"active","version":"1.4.0","language":"javascript","source_language":"en","source_url":"https://github.com/flmnt/graphemer","tags":["javascript","utf-8","strings","emoji","split","typescript"],"install":[{"cmd":"npm install graphemer","lang":"bash","label":"npm"},{"cmd":"yarn add graphemer","lang":"bash","label":"yarn"},{"cmd":"pnpm add graphemer","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"Graphemer is exported as a default export in ESM. Attempting a named import will result in an error.","wrong":"import { Graphemer } from 'graphemer';","symbol":"Graphemer","correct":"import Graphemer from 'graphemer';"},{"note":"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.","wrong":"const Graphemer = require('graphemer');","symbol":"Graphemer (CommonJS)","correct":"const Graphemer = require('graphemer').default;"}],"quickstart":{"code":"import Graphemer from 'graphemer';\n\nconst splitter = new Graphemer();\n\nconst emojiString = 'Hello 🏳️‍🌈 world! 👋🏽';\nconst hindiString = 'अनुच्छेद'; // 5 user-perceived letters\nconst zalgoString = 'Z͑ͫ̓ͪ̂ͫ̽͏̴̙̤̞͉͚̯̞̠͍A̴̵̜̰͔ͫ͗͢L̠ͨͧͩ͘G̴̻͈͍͔̹̑͗̎̅͛́Ǫ̵̹̻̝̳͂̌̌͘';\n\nconsole.log('Original emoji string length:', emojiString.length); // 19\nconst emojiGraphemes = splitter.splitGraphemes(emojiString);\nconsole.log('Split emoji graphemes:', emojiGraphemes); // ['H', 'e', 'l', 'l', 'o', ' ', '🏳️‍🌈', ' ', 'w', 'o', 'r', 'l', 'd', '!', ' ', '👋🏽']\nconsole.log('Emoji grapheme count:', emojiGraphemes.length); // 16\n\nconst hindiGraphemes = splitter.splitGraphemes(hindiString);\nconsole.log('Hindi grapheme count:', hindiGraphemes.length); // 5\n\nconst zalgoGraphemes = splitter.splitGraphemes(zalgoString);\nconsole.log('Zalgo grapheme count:', zalgoGraphemes.length); // 5\n\n// Iterate through graphemes\nfor (const grapheme of splitter.iterateGraphemes(emojiString)) {\n  console.log('Iterated grapheme:', grapheme);\n}\n\n// Get count directly\nconst count = splitter.countGraphemes(emojiString);\nconsole.log('Direct grapheme count:', count);\n","lang":"typescript","description":"Demonstrates initializing Graphemer and using `splitGraphemes`, `iterateGraphemes`, and `countGraphemes` with complex Unicode strings including emojis, combining marks, and Zalgo text."},"warnings":[{"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.","message":"Older 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.","severity":"breaking","affected_versions":"<1.4.0"},{"fix":"When using CommonJS, import `Graphemer` as `const Graphemer = require('graphemer').default;`.","message":"Mixing 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'.","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"fix":"Change `const Graphemer = require('graphemer');` to `const Graphemer = require('graphemer').default;`.","cause":"Attempting to instantiate `Graphemer` from a CommonJS `require` call without accessing the `.default` property.","error":"TypeError: Graphemer is not a constructor"},{"fix":"Change `import { Graphemer } from 'graphemer';` to `import Graphemer from 'graphemer';`.","cause":"Attempting to use a named import for `Graphemer` when it is a default export in ESM.","error":"SyntaxError: Named export 'Graphemer' not found. The requested module 'graphemer' does not provide an export named 'Graphemer'"}],"ecosystem":"npm"}