Knowledge baseExam Center
ENEnglish
Choose language13

CKTIS / JavaScript

Unicode code points versus grapheme clusters

JavaScript measures string length in UTF-16 code units, iterates by code point, and uses `Intl.Segmenter` to find grapheme cluster boundaries.

Version: ECMAScript 2024 and the current web platform; runtime support varies

Syntax

text.length
text[i]
[...text]
new Intl.Segmenter(locale, { granularity: "grapheme" }).segment(text)

A Unicode code point is a numeric value, such as U+0065 for e. In well-formed UTF-16 text, one Unicode scalar value occupies one or two 16-bit code units. In JavaScript, text.length counts code units, and text[i] and text.slice() use code-unit offsets. Cutting at such an offset can split a surrogate pair.

[...text] and for...of use the string iterator. It keeps valid surrogate pairs together, yields a lone surrogate on its own, and does not group code points into grapheme clusters. A grapheme cluster is a sequence of one or more code points that approximates a user-perceived character. For example, e followed by the combining acute accent U+0301 forms one cluster.

To count user-perceived characters or truncate text without cutting inside a cluster, use Intl.Segmenter with { granularity: "grapheme" }. The segment(text) method returns an iterable whose records include the segment text and its zero-based starting index in UTF-16 code units. You can pass that offset directly to slice().

Check for Intl.Segmenter in your target runtime. Boundaries can vary by implementation and locale. If the API is unavailable, do not substitute code-point iteration for grapheme segmentation: they are different operations.

Examples

{
  if (typeof globalThis.Intl?.Segmenter !== "function") {
    throw new Error("Intl.Segmenter is required for this example.");
  }

  const text = "e\u0301\u{1F600}";
  const segmenter = new Intl.Segmenter("en", { granularity: "grapheme" });
  const graphemes = [...segmenter.segment(text)];

  console.log(`UTF-16 code units: ${text.length}`);
  console.log(`Code points: ${[...text].length}`);
  console.log(`Grapheme clusters: ${graphemes.length}`);
  console.log(`Segment start offsets: ${graphemes.map(({ index }) => index).join(", ")}`);
}

Result

UTF-16 code units: 4
Code points: 3
Grapheme clusters: 2
Segment start offsets: 0, 2

The `e` and combining accent form the first cluster. The emoji forms the second, starts at offset `2`, and occupies two code units. The expected counts are 4 code units, 3 code points, and 2 clusters.

Related lessons

  • JavaScript · Lesson 15 · Advanced · Version: 4

Sources