JavaScript Reference Β· String
Strings and Unicode
How JavaScript strings store text: UTF-16 code units, code points, surrogate pairs, normalization and grapheme clusters, with runnable examples.
A JavaScript string is a sequence of 16-bit values called UTF-16 code units. That one fact explains most of the surprises with emoji, accents and non-Latin scripts. Text can be viewed at three levels: code units, code points and graphemes, and different parts of the language work at different levels.
This concept page explains the three levels, shows which feature uses which, and lists the tools for normalizing and validating text.
Try it
Press Run (or Ctrl + Enter) to see the console output here.
No output.
Press Run (or Ctrl + Enter) to see the console output here.
No output.
The three levels
Code units
A code unit is one 16-bit number. length, indexing (text[i]), charAt(), charCodeAt(), slice(), substring() and split("") all count and cut in code units. Characters up to U+FFFF fit in one unit.
Code points
A code point is a number from 0 to 0x10FFFF that identifies one Unicode character. Those above 0xFFFF are stored as a surrogate pair: a high surrogate (0xD800-0xDBFF) followed by a low one (0xDC00-0xDFFF). Code-point-aware features are the string iterator (for...of, spread), codePointAt(), String.fromCodePoint(), the u and v flags of regular expressions, and \u{1F600} escapes.
Graphemes
A grapheme cluster is what a reader sees as one symbol. A flag, an emoji with a skin tone, a family emoji joined with zero-width joiners, or a letter plus several combining marks can each be many code points. JavaScript has no built-in string method for graphemes; use Intl.Segmenter with granularity: "grapheme".
Normalization
The same visible text can be encoded in different ways. normalize() converts to a canonical form: "NFC" (compose, the usual choice for storage and comparison), "NFD" (decompose), and the compatibility forms "NFKC" and "NFKD", which also fold things like full-width letters and ligatures. Normalize both sides before comparing user input, file names or search terms.
Well-formed strings
JavaScript strings may contain lone surrogates, which are not valid Unicode text. isWellFormed() detects them and toWellFormed() replaces each with U+FFFD. Functions that must produce valid UTF-8, such as encodeURIComponent() and TextEncoder, throw or replace when they meet one, so clean external data first.
Usage notes
- Pick the right tool: counting limits in storage uses code units or bytes (
new TextEncoder().encode(text).lengthfor UTF-8 bytes); cutting visible text uses graphemes. - Case mapping is not one-to-one.
"Γ".toUpperCase()is"SS", so the length can change. UsetoLocaleUpperCase("tr")for locale rules such as Turkish dotted I. - Comparing order:
<compares code units, not alphabet order. UselocaleCompare()orIntl.Collatorfor sorting names. - Regular expressions: without the
uorvflag,.matches one code unit and/^.$/.test("π")isfalse. - Source files are Unicode text; escapes like
Γ©and\u{1F600}keep code portable.
Browser support
Code units, code points, normalize() and the u flag are supported everywhere. isWellFormed() and toWellFormed() are more recent, and Intl.Segmenter is available in current browsers; check a compatibility table if you support older ones.