Lesson guide

Learning objectives

  • Explain the main purpose of TextDecoder and TextEncoder in JavaScript.
  • Identify the syntax, APIs, or concepts introduced in this lesson.
  • Use the examples to predict how JavaScript will behave before you run similar code.
  • Connect this topic to nearby lessons in Binary data, files.

Real-world context

This lesson matters when you need to recognize where TextDecoder and TextEncoder fits into real JavaScript programs. What if the binary data is actually a string?

Key ideas

  • TextDecoder and TextEncoder is part of the Binary data, files chapter, so it builds on the surrounding concepts rather than standing alone.
  • Read each code example in two passes: first for the result, then for the rule that explains the result.
  • When a section compares similar features, focus on the condition that makes you choose one feature over another.

Key terms

  • TextDecoder and TextEncoder
  • TextDecoder
  • TextEncoder
  • Binary data, files
  • JavaScript

What if the binary data is actually a string? For instance, we received a file with textual data.

The built-in TextDecoder object allows one to read the value into an actual JavaScript string, given the buffer and the encoding.

We first need to create it:

javascript
let decoder = new TextDecoder([label], [options]);

  • label – the encoding, utf-8 by default, but big5, windows-1251 and many other are also supported.

  • options– optional object:

    • fatal – boolean, if true then throw an exception for invalid (non-decodable) characters, otherwise (default) replace them with character \uFFFD.
    • ignoreBOM – boolean, if true then ignore BOM (an optional byte-order Unicode mark), rarely needed.

…And then decode:

javascript
let str = decoder.decode([input], [options]);

  • input – BufferSource to decode.

  • options– optional object:

    • stream – true for decoding streams, when decoder is called repeatedly with incoming chunks of data. In that case a multi-byte character may occasionally split between chunks. This options tells TextDecoder to memorize “unfinished” characters and decode them when the next chunk comes.

For instance:

javascript
let uint8Array = new Uint8Array([72, 101, 108, 108, 111]);

alert( new TextDecoder().decode(uint8Array) ); // Hello
javascript
let uint8Array = new Uint8Array([228, 189, 160, 229, 165, 189]);

alert( new TextDecoder().decode(uint8Array) ); // 你好

We can decode a part of the buffer by creating a subarray view for it:

javascript
let uint8Array = new Uint8Array([0, 72, 101, 108, 108, 111, 0]);

// the string is in the middle
// create a new view over it, without copying anything
let binaryString = uint8Array.subarray(1, -1);

alert( new TextDecoder().decode(binaryString) ); // Hello

TextEncoder

TextEncoder does the reverse thing – converts a string into bytes.

The syntax is:

javascript
let encoder = new TextEncoder();

The only encoding it supports is “utf-8”.

It has two methods:

  • encode(str) – returns Uint8Array from a string.
  • encodeInto(str, destination) – encodes str into destination that must be Uint8Array.
javascript
let encoder = new TextEncoder();

let uint8Array = encoder.encode("Hello");
alert(uint8Array); // 72,101,108,108,111

Common mistakes

  • Skipping the small examples and then missing the exact rule that TextDecoder and TextEncoder depends on.
  • Copying code without changing one value at a time to see which part controls the result.
  • Treating similar-looking syntax or APIs as interchangeable before checking their edge cases.

Summary

  • TextDecoder and TextEncoder gives you one more piece of the JavaScript mental model.
  • The examples in this lesson are the quickest way to check whether the rule is clear.
  • Revisit the key terms when you meet the same idea in later chapters.

Predict

Before running this text-binary check, predict the five output lines. It decodes ASCII bytes, decodes UTF-8 bytes, decodes a subarray without copying, encodes text back to bytes, and handles a split multi-byte character with streaming.

javascript
Reveal explanation

The output is ascii:Hello, utf8:你好, subarray:Hello, encoded:72,105,33, and stream:0:€. TextDecoder turns bytes into JavaScript strings using an encoding, UTF-8 by default. A subarray view can decode only the meaningful bytes without copying the original buffer. TextEncoder performs the reverse operation and always produces UTF-8 bytes. The euro sign is three bytes in UTF-8; with { stream: true }, the decoder keeps the unfinished first two bytes and emits the character only when the final byte arrives.

Try it

Remove { stream: true } from the first chunk, then predict why the split character can no longer be reconstructed cleanly.

Practice

  • Rewrite one example from this lesson without looking at the original, then run it and compare the result.
  • Change one input, operator, method call, or option in a code sample and predict what will happen before running it.
  • Explain TextDecoder and TextEncoder in your own words as if you were reviewing it with another learner.

Keep learning

Continue with Blob when you are ready for the next lesson.