What Is a Grapheme Cluster?

Grapheme clusters at a glance

A grapheme cluster answers “What does the user see as one character?” Code points and code units describe lower-level Unicode and encoding representations.

What exactly is a grapheme cluster?

A grapheme cluster is a sequence of Unicode code points treated as one text element. It often corresponds to what a user perceives as one character, may contain one code point or several, and is a text-segmentation concept, not an encoding. It is independent of UTF-8 or UTF-16 storage and depends on Unicode grapheme-boundary rules used for cursor movement, deletion, selection and visible-character counting.

Use the Unicode Sequence Analyzer or Unicode Character Counter to inspect these layers.

Grapheme cluster vs code point

A code point is one Unicode value. A grapheme cluster may contain one or several code points, so code-point count is not always visible-character count. Some visible characters use precomposed code points; others use a base character plus combining marks or emoji sequence code points.

é
Precomposed: U+00E9
Decomposed: U+0065 U+0301

The two strings may look identical while containing different code-point sequences. Read What Is a Unicode Code Point?, Code Points vs Code Units and try the Unicode Normalizer.

Grapheme cluster vs code unit

Code units belong to a particular encoding. UTF-8 uses 8-bit code units and UTF-16 uses 16-bit code units. One grapheme may require many code units, while grapheme count does not depend on whether text is stored as UTF-8 or UTF-16.

😀
1 grapheme cluster
1 code point
4 UTF-8 code units
2 UTF-16 code units

👨‍👩‍👧‍👦 may be one grapheme cluster while using many code points, UTF-8 bytes and UTF-16 code units.

Interactive grapheme-cluster analyzer

This local component segments text into clusters, shows boundaries and lists contained code points, bytes and UTF-16 code units.

Combining characters

A combining character modifies a preceding base character. Combining marks can represent accents, vowel signs and other modifications; they usually do not form separate user-perceived characters. Multiple marks may follow one base, and rendering depends on font support and shaping.

e + ◌́ → é
U+0065 U+0301

a + ◌̊ → å

Combining sequences can be canonically equivalent to precomposed characters. Inspect with Unicode Character Inspector, Unicode Normalizer and Unicode Normalization Checker.

Emoji modifier sequences

Some emoji use a base emoji plus a modifier. Skin-tone modifiers are separate code points, and the combined sequence is usually one grapheme cluster. Removing part of the sequence changes the displayed result.

👍🏽
U+1F44D THUMBS UP SIGN
U+1F3FD EMOJI MODIFIER FITZPATRICK TYPE-4

1 grapheme cluster
2 code points
8 UTF-8 bytes
4 UTF-16 code units

The exact artwork depends on the platform.

Zero-width joiner emoji sequences

U+200D is ZERO WIDTH JOINER. It can join emoji into a single displayed sequence while the code points remain separate. Composite emoji can represent a family, profession or other sequence, and unsupported platforms may show separate emoji.

👨‍👩‍👧‍👦
MAN
ZWJ
WOMAN
ZWJ
GIRL
ZWJ
BOY

Flag emoji and regional indicators

Many flag emoji use pairs of regional indicator symbols. Each regional indicator is a separate code point, and a valid pair may display as one flag grapheme cluster. Unsupported systems may show separate symbols or letters.

🇺🇸
U+1F1FA REGIONAL INDICATOR SYMBOL LETTER U
U+1F1F8 REGIONAL INDICATOR SYMBOL LETTER S

1 grapheme cluster
2 code points
8 UTF-8 bytes
4 UTF-16 code units

Variation selectors

Variation selectors request a particular presentation. U+FE0E commonly requests text presentation, while U+FE0F commonly requests emoji presentation. The base character and variation selector may form one grapheme cluster, and selectors are usually invisible by themselves.

♥
♥️

The sequences can differ even when similar. Use the Invisible Character Detector and Unicode Sequence Analyzer.

What is an extended grapheme cluster?

Unicode text segmentation defines grapheme-boundary rules. Extended grapheme clusters are the practical default used by modern software because they handle combining marks, emoji sequences, regional indicators and script-specific behavior better than legacy clusters. For most application development, “grapheme cluster” should mean an extended grapheme cluster as defined by Unicode text-segmentation rules.

They are useful for interaction, but they do not perfectly match linguistic characters in every language. Boundaries can evolve as Unicode rules are updated, so applications should use maintained Unicode-aware libraries rather than manually coding a few special cases.

Grapheme boundaries and Unicode text segmentation

Unicode Standard Annex #29 defines default grapheme-cluster boundaries. Boundary rules determine where software may split text, using properties such as grapheme-break classes. Some boundaries are suppressed around combining marks, emoji modifiers, ZWJ sequences and regional indicators. Default segmentation may be tailored for specific languages or product behavior, and Unicode-version updates can change behavior.

A | é | 👍🏽 | 🇺🇸 | 👨‍👩‍👧‍👦

Each vertical line represents a grapheme boundary. The full algorithm belongs in maintained libraries, not ad hoc application code.

Why string length can be misleading

Standard length functions may count bytes, UTF-16 code units, code points or grapheme clusters. No single length function is correct for every requirement.

For 👨‍👩‍👧‍👦, byte, code-unit, code-point and grapheme counts all differ.

Grapheme clusters in JavaScript

JavaScript strings use UTF-16 code units. String.length does not count visible characters, and spread syntax iterates code points, not grapheme clusters. Intl.Segmenter is preferred where available.

const text = "👨‍👩‍👧‍👦";

console.log(text.length);
console.log([...text].length);

const segmenter = new Intl.Segmenter("en", {
    granularity: "grapheme",
});

const graphemes = [...segmenter.segment(text)];
console.log(graphemes.length); // Usually 1
console.log(graphemes.map(item => item.segment));

function splitGraphemes(text, locale = "en") {
    const segmenter = new Intl.Segmenter(locale, {
        granularity: "grapheme",
    });

    return [...segmenter.segment(text)].map(item => item.segment);
}

Check support and use a fallback library for older environments.

Grapheme clusters in Python

Python iteration normally yields code points, and len() does not count grapheme clusters. The standard library does not provide a direct extended-grapheme iterator, so a maintained library may be needed.

import regex

text = "👨‍👩‍👧‍👦"
graphemes = regex.findall(r"\X", text)

print(len(graphemes))
print(graphemes)

text = "e\u0301"

print(len(text))  # 2 code points
print(len(regex.findall(r"\X", text)))  # 1 grapheme cluster

\X matches an extended grapheme cluster in Unicode-aware regex implementations. Pin and test the dependency against the Unicode version you use.

Grapheme clusters in PHP

PHP strings are byte sequences. strlen() counts bytes. mb_strlen() is multibyte-aware but should not automatically be described as grapheme-aware. The Intl extension provides grapheme functions when available.

$text = "👨‍👩‍👧‍👦";

echo strlen($text);
echo mb_strlen($text, "UTF-8");
echo grapheme_strlen($text);

$text = "Aé👍🏽";
$length = grapheme_strlen($text);

for ($index = 0; $index < $length; $index++) {
    $cluster = grapheme_substr($text, $index, 1);
    echo $cluster . PHP_EOL;
}

Use intl for grapheme functions and mbstring for multibyte operations.

Safe text truncation

Byte-safe truncation is for payload, file-size and encoded storage limits and must not cut a UTF-8 sequence. Code-point-safe truncation applies only when the requirement limits Unicode scalar values and may still split a visible grapheme. Grapheme-safe truncation is usually right for usernames, display names, chat previews, buttons, labels, editor cursor behavior and user-facing character limits.

Safe deletion and cursor movement

Backspace should normally remove one grapheme cluster. Cursor movement should avoid stopping between a base character and combining mark, and editors should avoid placing the caret inside a ZWJ emoji sequence. Selection boundaries should respect grapheme segmentation when practical. Low-level APIs may expose code-unit indexes even when the UI acts on grapheme clusters. Bidirectional text and shaping add complexity beyond grapheme segmentation.

Character limits in forms and usernames

Product requirements must specify the unit. Database capacity and API limits may be byte-based, security checks may inspect code points, and user-facing limits should usually count grapheme clusters. Normalization can alter code-point and byte counts, while confusable and invisible characters require separate validation. A grapheme limit alone does not prevent abuse with very long combining sequences.

1. Validate encoded byte limit.
2. Validate Unicode scalar values.
3. Normalize only when required.
4. Count grapheme clusters for user-facing limits.
5. Limit pathological combining sequences.
6. Detect invisible or disallowed controls.
7. Apply product-specific script or identifier rules.

Use Invisible Character Detector, Confusable Character Detector, Unicode Normalizer and Unicode Character Counter.

Common grapheme-cluster mistakes

Treating JavaScript length as visible characters

It counts UTF-16 code units.

Treating spread syntax as grapheme-aware

Spread syntax iterates code points.

Treating Python length as grapheme count

It normally counts code points.

Treating mb_strlen() as sufficient for every UI limit

Multibyte-aware length and grapheme-aware length solve different problems.

Splitting text by arbitrary code-point indexes

Combining sequences and emoji can break.

Truncating UTF-8 by bytes without validation

This can create broken sequences.

Deleting only part of an emoji sequence

You can leave orphaned modifiers or joiners.

Assuming normalization produces one code point per grapheme

Normalized text can still contain multi-code-point clusters.

Assuming one grapheme has a fixed visual width

Emoji, CJK characters, combining marks and fonts vary.

Implementing segmentation with a simple regular expression

Unicode grapheme-boundary rules are more complex.

Ignoring Unicode-version changes

Segmentation data and rules evolve.

Practical debugging workflow

1. Preserve the original text.
2. Count encoded bytes.
3. Inspect code points.
4. Inspect UTF-16 code units where relevant.
5. Segment grapheme clusters.
6. Check normalization.
7. Detect combining marks.
8. Detect zero-width joiners and variation selectors.
9. Test cursor movement and deletion.
10. Test with accented text, emoji, flags and non-Latin scripts.

Start with Unicode Sequence Analyzer, Unicode Character Counter, Unicode Character Inspector, Unicode Normalizer, Invisible Character Detector and Unicode Text Compare.

Try these UnicodeNow tools

These tools help inspect graphemes, code points, byte length, normalization and hidden characters in real input.

Frequently asked questions

References

• The Unicode Standard
• Unicode glossary
• Unicode Standard Annex #29: Unicode Text Segmentation
• Unicode Standard Annex #15: Unicode Normalization Forms
• Unicode Character Database
• Unicode emoji data
• MDN: Intl.Segmenter
• MDN: JavaScript strings
• Python regex package documentation
• PHP manual: grapheme functions
• ICU boundary analysis