CKTIS / JavaScript
UTF-16 code units and surrogate pairs
JavaScript string length counts UTF-16 code units, not Unicode code points or user-perceived characters. The distinction matters when indexing, slicing, or iterating over text.
Version: ECMAScript 2024 and the current web platform; runtime support varies
Syntax
s.length; s[i]; s.slice(start, end); s.charCodeAt(i); s.codePointAt(i); [...s]; s.isWellFormed(); s.toWellFormed(); new Intl.Segmenter(undefined, { granularity: "grapheme" }).segment(s)UTF-16 code units and surrogate pairs explain why one code point can occupy two string indices. In ECMAScript 2024, a String value is a sequence of 16-bit code units. In well-formed UTF-16, a Unicode scalar value from U+0000 to U+FFFF (excluding U+D800–U+DFFF) takes one unit. A value from U+10000 to U+10FFFF takes two: a high surrogate (0xD800–0xDBFF) immediately followed by a low surrogate (0xDC00–0xDFFF). That pair encodes one code point.
s.length counts code units. s[i], s.slice(start, end), and s.charCodeAt(i) also use zero-based code-unit indices. At an in-range code-unit index, s[i] returns a string containing one code unit. At an out-of-range index, it returns undefined unless a corresponding property is found on the prototype chain. slice excludes end and can split a pair, and charCodeAt returns the numeric unit value (NaN out of range). s.codePointAt(i) uses the same kind of index: it returns the full numeric code point at the start of a pair, otherwise the numeric value of the single unit, even at the second half of a pair. It returns undefined out of range.
for...of and [...s] use the string iterator, which yields each valid pair together and every other unit separately, including lone surrogates. This is not grapheme segmentation: grapheme clusters approximate user-perceived characters. For example, e followed by a combining acute accent is two code points but one grapheme cluster. To segment text into graphemes, use Intl.Segmenter with granularity: "grapheme" where supported.
JavaScript permits lone surrogates in strings. s.isWellFormed() returns false if any are present. s.toWellFormed() returns a string with each lone surrogate replaced by U+FFFD, without changing the original. If well-formed UTF-16 is required, decide whether to reject or repair the input: replacement loses information. Check that these methods are available in your target runtime.
Examples
{
const s = "A\u{1F600}e\u0301";
const hex = n => n.toString(16).toUpperCase();
console.log(`length=${s.length}; iterator=${[...s].length}`);
console.log(`units=${hex(s.charCodeAt(1))} ${hex(s.charCodeAt(2))}`);
console.log(`codePointAt(1)=${hex(s.codePointAt(1))}; codePointAt(2)=${hex(s.codePointAt(2))}`);
console.log(`slice(1, 2) is lone high surrogate: ${s.slice(1, 2) === "\uD83D"}`);
}Result
length=5; iterator=4 units=D83D DE00 codePointAt(1)=1F600; codePointAt(2)=DE00 slice(1, 2) is lone high surrogate: true
The string has five code units and four iterator elements. Indices `1` and `2` address the two halves of the emoji; `slice(1, 2)` keeps only the high surrogate.
Related lessons
- JavaScript · Lesson 2 · Advanced · Version: 4