JavaScript String toWellFormed() Method

What You’ll Learn

String.prototype.toWellFormed() returns a new string with every lone UTF-16 surrogate replaced by the Unicode replacement character U+FFFD (�) (same API as MDN String.prototype.toWellFormed()). Learn why ill-formed text breaks encodeURI(), how valid emoji stay intact, pairing with isWellFormed(), 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. When only one half arrives, you get a lone surrogate — an ill-formed string.

toWellFormed() repairs that by swapping each orphan for U+FFFD (�), the standard Unicode replacement character. Engines can do this efficiently against the internal string data.

This page is part of JavaScript String Methods. Related topics include isWellFormed() and normalize().

Understanding the toWellFormed() Method

str.toWellFormed() walks the UTF-16 code units and replaces any unpaired high or low surrogate with U+FFFD. Complete pairs (real emoji) stay as they are.

• Returns a new string — always (even if already well-formed).
• Takes no parameters.
• Lone surrogates become � (U+FFFD).
• Does not change Unicode normalization — use normalize() for NFC/NFD.

📝 Syntax

General form of String.prototype.toWellFormed:

str.toWellFormed()

Parameters

• None — this method does not accept arguments.

Return value

A new string that is a copy of this string, with all lone surrogates replaced with U+FFFD. If the string was already well-formed, you still get a new string with the same content.

Exceptions

None for normal string values.

Common patterns

"ab\uD800".toWellFormed();           // "ab�"
"abc".toWellFormed();                // "abc"
"ab\uD83D\uDE04c".toWellFormed();    // "ab😄c" (valid pair kept)
encodeURI(illFormed.toWellFormed()); // safe — no URIError

Examples Gallery

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

const strings = [
  // Lone leading surrogate
  "ab\uD800",
  "ab\uD800c",
  // Lone trailing surrogate
  "\uDFFFab",
  "c\uDFFFab",
  // Well-formed
  "abc",
  "ab\uD83D\uDE04c",
];

for (const str of strings) {
  console.log(str.toWellFormed());
}
// "ab�"
// "ab�c"
// "�ab"
// "c�ab"
// "abc"
// "ab😄c"

ab�
ab�c
�ab
c�ab
abc
ab😄c

const emoji = "😄";
const fixed = emoji.toWellFormed();

console.log(fixed);                    // "😄"
console.log(fixed === emoji);          // true (same content)
console.log(fixed.isWellFormed());     // true
console.log("hello".toWellFormed());   // "hello"

😄
true
true
hello

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

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

console.log(encodeURI(illFormed.toWellFormed()));
// "https://example.com/search?q=%EF%BF%BD"

URIError
https://example.com/search?q=%EF%BF%BD

function sanitize(text) {
  if (!text.isWellFormed()) {
    return text.toWellFormed();
  }
  return text;
}

const raw = "hi\uD800";
const safe = sanitize(raw);

console.log(raw.isWellFormed());   // false
console.log(safe.isWellFormed());  // true
console.log(safe);                 // "hi�"

false
true
hi�

const smile = "😀";
const half = smile.slice(0, 1);

console.log(half.isWellFormed());           // false
console.log(half.toWellFormed());           // "�"
console.log(half.toWellFormed().isWellFormed()); // true

false
�
true

🎯 Common Use Cases

• Safe URIs — encodeURI(str.toWellFormed()) before networking.
• Sanitize imports — text from buffers, files, or cut-and-paste bugs.
• Detect + repair pipelines — pair with isWellFormed().
• Not for NFC/NFD — use normalize() for composed vs decomposed forms.
• Not everyday English — normal literals rarely need this.

📝 Notes

• Always returns a new string, even when nothing needed fixing.
• Same replacement character many APIs use automatically (for example TextEncoder).
• Slicing mid-emoji with slice / charAt is a common source of lone surrogates.
• Not the same as normalize() — that changes Unicode forms, not surrogates.
• Baseline widely available since October 2023 — polyfill older runtimes if required.

💡 Best Practices