Unicode, code units and length

A string is a sequence of UTF-16 code units, and a code unit is sixteen bits. Most characters of most alphabets fit in one unit, and a character outside the basic plane takes two, which is why length of one emoji is two and why a loop over indices can split a character in half. This is not a JavaScript quirk: UTF-16 is the encoding the language was specified with, and the same counting appears in Java and in Windows APIs.

The fix is to iterate instead of counting. The spread and Array.from walk the string by code point, and for...of does the same in a loop. One step further is the grapheme cluster, which is what a reader calls a character: a flag or a family emoji is several code points that are drawn as one. The last section measures all three counts on the same text.

Code units

length counts code units and charCodeAt returns the number of one of them. A letter of the Latin alphabet, an accented letter written as one unit and the euro sign are all one unit wide, and the codes are the numbers of the Unicode standard. The value 233 is the accented e and 8364 is the euro.

const ascii = 'A'; const accented = 'é'; const euro = '€'; console.log('A:', 'length', ascii.length, 'code', ascii.charCodeAt(0)); console.log('é:', 'length', accented.length, 'code', accented.charCodeAt(0)); console.log('€:', 'length', euro.length, 'code', euro.charCodeAt(0)); console.log('from codes:', String.fromCharCode(65, 233)); console.log('upper of é:', accented.toUpperCase(), accented.toUpperCase().length);

node units.js

A: length 1 code 65
é: length 1 code 233
€: length 1 code 8364
from codes: Aé
upper of é: É 1

A character of the basic plane is one number here, so length agrees with what a reader counts. The last line is a warning about the other direction: the uppercase of the accented e is one unit too, and the uppercase of the German sharp s is two, so a case conversion can change the length of a string. A program that stores a byte offset and later finds the string longer has met this.

Code points above the basic plane

A character above the basic plane, which is most emoji and the less common scripts, needs a pair of units called a surrogate pair. length counts two, charCodeAt gives the two halves and codePointAt gives the real number. The number is what the Unicode charts print, and String.fromCodePoint is the way back.

const emoji = '😀'; console.log('length:', emoji.length); console.log('units:', emoji.charCodeAt(0), emoji.charCodeAt(1)); console.log('code point:', emoji.codePointAt(0)); console.log('in hex:', emoji.codePointAt(0).toString(16)); console.log('from the point:', String.fromCodePoint(0x1f600) === emoji); console.log('from the pair:', String.fromCharCode(0xd83d, 0xde00) === emoji); console.log('two halves:', emoji[0] + emoji[1] === emoji, emoji[0].length);

node points.js

length: 2
units: 55357 56832
code point: 128512
in hex: 1f600
from the point: true
from the pair: true
two halves: true 1

The two units are the numbers of the surrogate pair, and the code point is the one the chart lists: 0x1f600 in hexadecimal is the grinning face. Both constructors rebuild the string, and the last line shows why an index is the wrong way to read a character: each half is a string of its own that means nothing alone. A program that validates user text by walking indices accepts half a character as a value.

Array.from and for...of

The iterator of a string yields code points rather than units, so the spread, Array.from and for...of all count a surrogate pair as one element. That is the count to use for a character limit and for anything that reverses or slices a string by characters. The loop below prints each character with the number of units it took.

const text = 'a😀b'; console.log('length:', text.length); console.log('spread:', [...text].length); console.log('Array.from:', Array.from(text).length); for (const char of text) { console.log('char:', char, 'units:', char.length); } console.log('reversed:', [...text].reverse().join(''));

node iterating.js

length: 4
spread: 3
Array.from: 3
char: a units: 1
char: 😀 units: 2
char: b units: 1
reversed: b😀a

The four units of the string are three characters, and the loop printed one line per character with the unit count beside it. The reversal is correct here because each element of the array is a whole code point, while text.split('').reverse() would cut the emoji into two halves and print a broken character. A code point limit is still not a limit on what a reader sees, which is the subject of the last section.

The characters a reader sees

A flag is two code points and a family emoji is four joined by zero-width joiners, and a reader counts each of them as one character. The unit that a reader sees is the grapheme cluster, and Intl.Segmenter splits a string into them. The program prints the unit count, the code point count and the grapheme count for the same two strings, with the locale and the granularity passed explicitly.

const flag = '🇬🇧'; const family = '👨‍👩‍👧‍👦'; const segmenter = new Intl.Segmenter('en', { granularity: 'grapheme' }); console.log('flag units:', flag.length); console.log('flag code points:', [...flag].length); console.log('flag graphemes:', [...segmenter.segment(flag)].length); console.log('family units:', family.length); console.log('family code points:', [...family].length); console.log('family graphemes:', [...segmenter.segment(family)].length); console.log('family graphemes as text:', [...segmenter.segment(family)].length === 1);

node graphemes.js

flag units: 4
flag code points: 2
flag graphemes: 1
family units: 11
family code points: 7
family graphemes: 1
family graphemes as text: true

Three counts for one visible character, and the largest is the one length reports. A text field with a limit of twenty characters has to decide which count it means, and the answer a person expects is the grapheme one. The segmenter also splits words and sentences with the other granularities, which is how a program breaks text into lines for a language without spaces.

Exercises

  1. Print the length of 'e\u0301' and of 'é' in units.js. Are they the same number, and do the two strings compare equal?
  2. Print emoji.codePointAt(1) in points.js. Which number arrives, and why is it the second half rather than the character?
  3. Count the characters of 'a😀b' with length, split('').length and [...text].length. Which two answers agree?
  4. Change the granularity of the segmenter to 'word' and count the pieces of 'one two three'. How many pieces does the segmenter return, and how many of them are words?
  5. Take the first six characters of a string with an emoji at position three, once with slice and once with Array.from(text).slice(0, 6).join(''). Which result is whole?

Questions

A new set of questions in a new order every time. Choose one answer for each, then check.

  1. What does length count in a JavaScript string?

    Answer

    UTF-16 code units

    The string is a sequence of sixteen-bit code units, and length counts those.

  2. What does this program print? console.log('😀'.length);

    Answer

    2

    The emoji is above the basic plane, so it is stored as a surrogate pair of two units.

  3. What does this program print? console.log([...'a😀b'].length);

    Answer

    3

    The spread yields code points, and the surrogate pair counts as one of them.

  4. What does this program print? console.log('😀'.codePointAt(0).toString(16));

    Answer

    1f600

    The code point of the grinning face is 0x1F600, and the surrogate halves are not it.

  5. Which construct iterates a string by code point?

    Answer

    for...of

    The loop over indices walks code units, and the iterator of the string walks code points.

  6. What does this program print? console.log('🇬🇧'.length);

    Answer

    4

    The flag is two regional indicators, and each of them is a surrogate pair of two units.

  7. What is a grapheme cluster?

    Answer

    The unit a reader sees as one character

    A family emoji is several code points joined, and the reader sees one character.

  8. Which tool splits a string into grapheme clusters?

    Answer

    Intl.Segmenter with the grapheme granularity

    The segmenter is the only one of the four that knows about joined characters.

  9. What does this program print? console.log([...'é'].length);

    Answer

    1

    The precomposed accented e is one code point and one code unit.

  10. Why is a character limit measured in graphemes the one a user expects?

    Answer

    Because it matches what the user sees on the screen

    A limit in units or code points cuts a visible character, and the form shows a broken glyph.

The code on this page was run with Node.js 24.22.1 and linted with ESLint 10.14.0 on Alpine Linux 3.24.3 (x86_64) in a Docker container.

Article author: Arthur Isaev