JavaScript String codePointAt() Method

What You’ll Learn

String.prototype.codePointAt() returns the full Unicode code point starting at a UTF-16 index (same API as MDN String.prototype.codePointAt()). Learn emoji / surrogate pairs, out-of-range undefined, how it differs from charCodeAt(), safe looping, five examples, and try-it labs.

Introduction

Unicode code points run from 0 to 0x10FFFF (over one million). JavaScript strings store text as UTF-16 code units (0–65535). Characters above U+FFFF — including many emoji — use two units (a surrogate pair).

charCodeAt() always returns one unit. codePointAt() returns the full character value when you start at the leading surrogate — so "😍".codePointAt(0) is 128525, not a half-emoji number.

This page is part of JavaScript String Methods. Related topics include charCodeAt() and charAt().

Understanding the codePointAt() Method

codePointAt(index) reads the Unicode code point that starts at that UTF-16 index. If the unit there is a leading surrogate with a matching trail, you get the combined code point.

• Indexes are zero-based UTF-16 positions — same as charAt.
• Valid results are integers from 0 to 0x10FFFF.
• Missing position — returns undefined.
• A trailing-surrogate-only index returns just that unit (not the full emoji).

📝 Syntax

General form of String.prototype.codePointAt:

str.codePointAt(index)

Parameters

• index — zero-based UTF-16 position where the character starts. Converted to an integer (undefined becomes 0).

Return value

A number (the Unicode code point) or undefined. Special cases:

Common patterns

"ABC".codePointAt(0);                 // 65
"😍".codePointAt(0);                  // 128525
"😍".codePointAt(0).toString(16);     // "1f60d"

String.fromCodePoint(128525);         // "😍"

// Iterate by code point (recommended):
[..."☃★😍"].map((ch) => ch.codePointAt(0));
// [9731, 9733, 128525]

Examples Gallery

Examples follow MDN String.codePointAt() patterns. Use View Output or Try It Yourself for each case.

const icons = "☃★♲";

icons.codePointAt(1);
// 9733

9733

"ABC".codePointAt(0);              // 65
"ABC".codePointAt(0).toString(16); // "41"

"😍".codePointAt(0);               // 128525
"😍".codePointAt(0).toString(16);  // "1f60d"

65
41
128525
1f60d

"😍".codePointAt(0);   // 128525  (full emoji)
"😍".codePointAt(1);   // 56845   (trailing surrogate only)

"😍".length;           // 2
"😍".charCodeAt(0);    // 55357   (high surrogate — not the full emoji)

String.fromCodePoint(128525);  // "😍"

128525
56845
2
55357
😍

const s = "Hi";

s.codePointAt();      // 72
s.codePointAt(0);     // 72
s.codePointAt(1);     // 105
s.codePointAt(2);     // undefined
s.codePointAt(-1);    // undefined
s.codePointAt(999);   // undefined

s.charCodeAt(2);      // NaN
s.charAt(2);          // ""

72
72
105
undefined
undefined
undefined
NaN
""

const str = "\ud83d\udc0e\ud83d\udc71\u2764";  // 🐎 + 👤 + ❤

// Prefer for...of or spread (iterate code points):
[...str].map((cp) => cp.codePointAt(0).toString(16));
// ["1f40e", "1f471", "2764"]

// Index loop visits trailing surrogates too — usually not what you want:
for (let i = 0; i < str.length; i++) {
  // may log half-emoji units as well as full points
  str.codePointAt(i).toString(16);
}

1f40e
1f471
2764

🚀 Common Use Cases

• Emoji & rare characters — get the real Unicode value, not a surrogate.
• Hex / U+ notation — codePointAt(0).toString(16) for docs and logs.
• Round-trip with fromCodePoint — rebuild characters from numeric IDs.
• Safe iteration — pair with for...of / [...str].
• Validation — check ranges for allowed symbols or scripts.
• Not for grapheme clusters — family emoji / skin tones may need Intl.Segmenter.

📝 Notes

• Indexes are UTF-16 code units, even though the return value is a code point.
• Out-of-range indexes return undefined, not NaN.
• Calling codePointAt() with no argument is the same as codePointAt(0).
• Starting on a trailing surrogate returns only that unit — start on the leading one for the full emoji.
• Prefer for...of / spread when iterating characters that may be emoji.
• Visible “characters” with modifiers (ZWJ sequences) may span multiple code points — use a segmenter when needed.

💡 Best Practices