Skip to content
Tutorials Center
My learning

Topics

JavaScript Reference ยท String

String.prototype.toWellFormed()

Reference for JavaScript String.prototype.toWellFormed(): replace lone UTF-16 surrogates with U+FFFD so a string is safe for encoders such as encodeURIComponent().

JavaScript strings are sequences of UTF-16 code units, and nothing stops a string from containing a lone surrogate: half of a surrogate pair without its partner. Such a string is not valid Unicode text, and some APIs refuse it. The toWellFormed() method returns a copy in which each lone surrogate is replaced by the replacement character U+FFFD (๏ฟฝ).

Use it before handing text to an API that needs valid Unicode, such as encodeURIComponent() or a protocol that requires valid UTF-8. To only test a string, use isWellFormed().

JavaScript
"ab\uD800".toWellFormed(); // "ab๏ฟฝ"

Try it

JS Repairing a broken string

Press Run (or Ctrl + Enter) to see the console output here.

No output.

JS Why encoders care

Press Run (or Ctrl + Enter) to see the console output here.

No output.

Syntax

JavaScript
string.toWellFormed()

This method takes no parameters.

Return value: a new string in which every lone surrogate (a code unit from \uD800 to \uDFFF that is not part of a correct high-then-low pair) is replaced by U+FFFD. A string that is already well formed is returned with identical contents.

Exceptions: none for strings.

Usage notes

  • A valid pair is kept. Emoji and other characters outside the Basic Multilingual Plane are stored as a high surrogate followed by a low surrogate; those are left alone.
  • The length does not change. Each lone surrogate is one code unit and U+FFFD is one code unit, so indexes stay the same.
  • Lossy: the original lone code unit is gone. If you need to preserve arbitrary binary data, do not store it in a string this way; use typed arrays.
  • Where lone surrogates come from: slicing through an emoji with slice(), substring() or split(""), truncating text at a fixed length, or reading corrupted data.
  • encodeURIComponent() throws a URIError on a lone surrogate, which is a common production crash when truncated user input is encoded. toWellFormed() prevents that.
  • TextEncoder is already forgiving: it replaces lone surrogates with U+FFFD in its output bytes, as the second example shows.
  • Check first, if you like: isWellFormed() avoids creating a copy when you only need to know.
  • Only surrogates are repaired. Other problems, such as unusual normalization forms, are not touched.

Browser support

This is a recent addition (ECMAScript 2024). It works in current browsers, but check a compatibility table before relying on it for older ones.