JavaScript String isWellFormed() Method

What You’ll Learn

String.prototype.isWellFormed() returns whether a string has any lone UTF-16 surrogates (same API as MDN String.prototype.isWellFormed()). Learn well-formed vs broken pairs, emoji that pass the check, guarding encodeURI(), pairing with toWellFormed(), five examples, and try-it labs.

Introduction

JavaScript strings are stored as UTF-16. Characters above U+FFFF (including many emoji) need two code units called a surrogate pair: a high (leading) surrogate plus a low (trailing) one.

Sometimes data arrives with only one half of that pair — a lone surrogate. That string is ill-formed. It may still look odd in the console, but APIs like encodeURI() can throw a URIError when they see it.

This page is part of JavaScript String Methods. Related topics include toWellFormed() and codePointAt().

Understanding the isWellFormed() Method

isWellFormed() scans the string for unpaired surrogates. Engines can do this efficiently against the internal UTF-16 data — faster and clearer than a hand-written loop.

• No parameters — just call str.isWellFormed().
• Returns true when every surrogate is part of a valid pair (or none exist).
• Returns false when any lone high or low surrogate is present.
• Does not fix the string — use toWellFormed() when you need a repaired copy.

📝 Syntax

General form of String.prototype.isWellFormed:

str.isWellFormed()

Parameters

• None — this method does not accept arguments.

Return value

A boolean. Special cases:

Common patterns

"hello".isWellFormed();           // true
"\uD800".isWellFormed();          // false  (lone high surrogate)
"😄".isWellFormed();              // true   (valid pair)

if (!text.isWellFormed()) {
  console.warn("Ill-formed UTF-16");
  text = text.toWellFormed();     // replace lone surrogates with U+FFFD
}

Examples Gallery

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

const strings = [
  "ab\uD800",           // lone leading surrogate
  "ab\uD800c",
  "\uDFFFab",           // lone trailing surrogate
  "c\uDFFFab",
  "abc",                // well-formed
  "ab\uD83D\uDE04c",    // well-formed (😄 pair)
];

for (const str of strings) {
  console.log(str.isWellFormed());
}
// false, false, false, false, true, true

false
false
false
false
true
true

const highOnly = "\uD800";   // high surrogate alone
const lowOnly = "\uDFFF";    // low surrogate alone
const pair = "\uD83D\uDE00"; // 😀

console.log(highOnly.isWellFormed()); // false
console.log(lowOnly.isWellFormed());  // false
console.log(pair.isWellFormed());     // true

console.log(highOnly.length); // 1
console.log(pair.length);     // 2

false
false
true
1
2

console.log("".isWellFormed());           // true
console.log("CodeToFun".isWellFormed());  // true
console.log("你好".isWellFormed());         // true
console.log("😀🎉".isWellFormed());       // true

// Broken: cut the emoji in half by taking only the first unit
const broken = "😀".charAt(0);
console.log(broken.isWellFormed());       // false
console.log(broken.charCodeAt(0));        // 55357 (high surrogate)

true
true
true
true
false
55357

const illFormed = "https://example.com/search?q=\uD800";

try {
  encodeURI(illFormed);
} catch (e) {
  console.log(e.name); // URIError
}

if (illFormed.isWellFormed()) {
  console.log(encodeURI(illFormed));
} else {
  console.warn("Ill-formed strings encountered.");
}

URIError
Ill-formed strings encountered.

const raw = "Hi \uD800 there";

console.log(raw.isWellFormed()); // false

const safe = raw.toWellFormed();
console.log(safe.isWellFormed()); // true
console.log(safe);                // "Hi � there"

console.log(encodeURI(safe));     // works — no URIError

false
true
Hi � there
Hi%20%EF%BF%BD%20there

🚀 Common Use Cases

• URI encoding — check before encodeURI / encodeURIComponent.
• Input validation — reject or flag text that arrived with broken surrogates.
• Binary / buffer decoding — verify strings built from raw UTF-16 units.
• Logging & APIs — avoid sending ill-formed payloads to systems that crash on them.
• Sanitize pipeline — isWellFormed() to decide; toWellFormed() to fix.
• Debugging emoji bugs — catch accidental charAt / slice cuts on pairs.

📝 Notes

• Takes no parameters — always call isWellFormed() with empty parentheses.
• Valid emoji and other supplementary characters use paired surrogates and return true.
• Slicing or charAt in the middle of an emoji can create ill-formed strings.
• This is not the same as Unicode normalization (normalize()) — that deals with composed vs decomposed forms.
• Prefer the built-in method over a custom surrogate loop — engines optimize the check.
• Baseline widely available since October 2023 — polyfill if you must support older runtimes.

💡 Best Practices