JavaScript Reference · Typed Arrays and Binary Data
TextEncoder and TextDecoder
Reference for TextEncoder and TextDecoder: convert strings to UTF-8 bytes and decode bytes back to text, with encodeInto(), fatal mode and other encodings.
Strings in JavaScript are sequences of UTF-16 code units, but files and networks speak bytes. TextEncoder turns a string into UTF-8 bytes, and TextDecoder turns bytes back into a string. Both are built for binary data: the encoder returns a Uint8Array and the decoder accepts any ArrayBuffer or typed array.
const bytes = new TextEncoder().encode("héllo"); const text = new TextDecoder().decode(bytes);
Try it
Press Run (or Ctrl + Enter) to see the console output here.
No output.
Press Run (or Ctrl + Enter) to see the console output here.
No output.
Syntax
const encoder = new TextEncoder(); encoder.encode(string) encoder.encodeInto(string, uint8Array) const decoder = new TextDecoder(label, { fatal, ignoreBOM }); decoder.decode(buffer, { stream })
| Name | Description |
|---|---|
string |
The text to encode. |
uint8Array |
For encodeInto(): the destination Uint8Array. |
label |
An encoding name such as "utf-8" (default), "utf-16le", "windows-1252" or "iso-8859-2". Case-insensitive; many aliases work. |
fatal |
If true, invalid input throws instead of producing U+FFFD. Default false. |
ignoreBOM |
If true, a leading byte order mark stays in the output; by default it is removed. |
buffer |
An ArrayBuffer, typed array or DataView holding the bytes. Omit it to flush pending state. |
stream |
Set true while more chunks are coming, so a character split across chunks decodes correctly. |
Return value: encode() returns a new Uint8Array. encodeInto() returns { read, written }: the number of UTF-16 units consumed and bytes written. decode() returns a string.
Exceptions: new TextDecoder(label) throws RangeError for an unknown label. With fatal: true, decode() throws TypeError on malformed bytes.
Usage notes
TextEncoderis always UTF-8. There is no option for other encodings; use another approach if you must produce, say, Latin-1 bytes.- Byte length is not string length. Non-ASCII characters take 2 to 4 bytes in UTF-8, so measure
encode(text).lengthwhen a limit is in bytes. - Lone surrogates in the input are replaced by
U+FFFDwhen encoding. See isWellFormed(). encodeInto()avoids allocation and never writes half a character; when the target is too small it stops early, whichreadandwrittenreport.- Reuse one encoder or decoder instead of creating one per call.
- Chunked data. Use
{ stream: true }, or the stream classesTextDecoderStreamandTextEncoderStream, when text arrives in pieces fromfetch(). - Base64. To base64-encode Unicode text, encode to bytes first (see btoa() and atob()).
Browser support
Both classes work in all current browsers and in Node.js and other runtimes. The set of non-UTF-8 labels follows the Encoding Standard; check a compatibility table for rare ones.