Skip to content
Tutorials Center
My learning

Topics

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.

JavaScript
const bytes = new TextEncoder().encode("héllo");
const text = new TextDecoder().decode(bytes);

Try it

JS Round trip through UTF-8

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

No output.

JS Invalid bytes and other encodings

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

No output.

Syntax

JavaScript
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

  • TextEncoder is 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).length when a limit is in bytes.
  • Lone surrogates in the input are replaced by U+FFFD when encoding. See isWellFormed().
  • encodeInto() avoids allocation and never writes half a character; when the target is too small it stops early, which read and written report.
  • Reuse one encoder or decoder instead of creating one per call.
  • Chunked data. Use { stream: true }, or the stream classes TextDecoderStream and TextEncoderStream, when text arrives in pieces from fetch().
  • 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.