JavaScript String isWellFormed() Method

Beginner
5 min read
Updated: Nov 2026
3 examples
Method
Decorative image with the word ISWELLFORMED

Definition

String.prototype.isWellFormed() returns true if the string has no lone UTF-16 surrogates, and false if any unpaired half is present. To fix broken text, use toWellFormed().

Pass the required arguments shown below. Check return values and browser support before you rely on the result.

Syntax

Call string.isWellFormed. Start with this line.

JavaScript
str.isWellFormed()
CallWhat it does
str.isWellFormed()Primary signature.
string.isWellFormed(...)Call with the arguments your case needs.

Built into JavaScript. Call isWellFormed(...) on a string (or String instance) — no import required.

Library declarations
JavaScript
str.isWellFormed()

Parameters

This member has no parameters beyond those shown in the signature.

Return Value

Return ValueDescription
*true or false

JavaScript Examples

Example 1 — Basic isWellFormed() Checks

Normal text and a valid emoji pair pass; a lone surrogate fails.

JavaScript
console.log("abc".isWellFormed());            // true
console.log("\uD83D\uDE00".isWellFormed());   // true  (😀)
console.log("\uD800".isWellFormed());         // false (lone high)
console.log("\uDFFF".isWellFormed());         // false (lone low)
Try It Yourself

How It Works

  1. Plain ASCII. No surrogates at all → true.
  2. Valid pair. High \uD83D followed by low \uDE00 → true.
  3. Lone high. \uD800 has no low partner → false.
  4. Lone low. \uDFFF alone is also invalid → false.

Example 2 — Accidental Cut with charAt(0)

Splitting an emoji by UTF-16 unit creates a lone surrogate.

JavaScript
const smile = "😀";
const broken = smile.charAt(0);

console.log(smile.isWellFormed());   // true
console.log(broken.isWellFormed());  // false
console.log(broken.length);          // 1
console.log(broken.charCodeAt(0));   // 55357 (high surrogate)
Try It Yourself

How It Works

  1. Full emoji. Two UTF-16 units that form a pair → well-formed.
  2. charAt takes one unit. Only the high surrogate remains.
  3. Check fails. That orphan makes isWellFormed() return false.
  4. Safer access. Prefer for...of or codePointAt(0) for full characters.

Example 3 — Detect, Then Repair

Guard risky APIs, or fix text with toWellFormed().

JavaScript
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
Try It Yourself

How It Works

  1. Detect. The lone \uD800 makes the check fail.
  2. Repair. toWellFormed() returns a new string with U+FFFD (�).
  3. Verify. The repaired string passes isWellFormed().
  4. Encode safely. encodeURI accepts well-formed UTF-16 and no longer throws.
Compatibility

Browser & Runtime Support

String.prototype.isWellFormed() is part of ES2024. It reached Baseline Widely available around October 2023.

✓ Baseline · ES2024

String.prototype.isWellFormed()

Supported in Chrome 111+, Firefox 119+, Safari 16.4+, Edge 111+, and Node.js 20+. Not available in Internet Explorer.

92% Modern browser support
Google Chrome Supported · Desktop & Mobile
Full support
Mozilla Firefox Supported · Desktop & Mobile
Full support
Apple Safari Supported · macOS & iOS
Full support
Microsoft Edge Supported · Chromium
Full support
Internet Explorer No native support · Use a polyfill
Polyfill
Opera Supported · Modern versions
Full support
Samsung Internet Supported · Android
Full support
Bun Supported · JavaScript runtime
Supported
Deno Supported · JavaScript runtime
Supported
Node.js Supported · Server runtime
Supported
Android WebView Supported · Modern WebView
Full support
String.isWellFormed() Excellent

Bottom line: Safe for modern web apps and current Node LTS (20+). For older targets, feature-detect with if ("isWellFormed" in String.prototype) and polyfill or fall back to a manual surrogate scan.

Frequently Asked Questions

isWellFormed() returns true if the string has no lone UTF-16 surrogates, and false if it contains any unpaired high or low surrogate.
UTF-16 uses pairs of code units for characters above U+FFFF (like many emoji). A lone surrogate is one half of that pair without its matching partner — for example "\uD800" alone.
No. Call it with empty parentheses: str.isWellFormed(). There is nothing to configure.
Before APIs that reject ill-formed strings (such as encodeURI()), when validating text from binary or network sources, or when you want to treat broken surrogate data differently from normal text.
isWellFormed() only checks and returns a boolean. toWellFormed() returns a new string where lone surrogates are replaced with the Unicode replacement character (U+FFFD).
No. Strings are immutable. isWellFormed() only reads and returns true or false.

Next: toWellFormed()

Replace lone surrogates with the Unicode replacement character so encoding stays safe.

toWellFormed() tutorial →

About the author

Mari Selvan M P
Mari Selvan M P 🔗

Developer, cloud engineer, and technical writer

  • Experience 12 years building web and cloud systems
  • Focus Full Stack Development, AWS, and Developer Education

I write practical tutorials so students and working developers can learn by doing—from databases and APIs to deployment on AWS.

AWS Certified Developer – Associate (Credly)

11 people found this page helpful

JavaScript String matchAll() Method JavaScript String toWellFormed() Method