Knowledge baseExam Center
ENEnglish
Choose language13

CKTIS / JavaScript

TextDecoder: decoding bytes, handling errors and preserving a BOM

Decode bytes into JavaScript text, choose how to handle malformed sequences and a leading byte order mark, and finish decoding input split across chunks.

Version: Current web platform; runtime support varies

Syntax

new TextDecoder()
new TextDecoder(label)
new TextDecoder(label, { fatal, ignoreBOM })
decoder.decode()
decoder.decode(input)
decoder.decode(input, { stream })
decoder.fatal
decoder.ignoreBOM

In TextDecoder.decode/fatal/ignoreBOM, decode() is the instance method: it returns a JavaScript string from optional byte input, such as an ArrayBuffer, typed array, or DataView. The new TextDecoder(label, options) constructor selects the encoding, defaulting to "utf-8". An unknown label or one that maps to the replacement encoding causes a RangeError at construction.

decoder.fatal and decoder.ignoreBOM are read-only booleans. Both default to false and are set through constructor options, not through decode(). With fatal: false, decoding errors produce the replacement character U+FFFD; with fatal: true, decode() throws TypeError. Strict decoding does not make the resulting text safe to use as HTML.

For UTF-8, UTF-16LE, and UTF-16BE, ignoreBOM: false omits a leading byte order mark (BOM), while ignoreBOM: true preserves it as U+FEFF in the result. In other words, true skips the special treatment, not the mark itself. This option neither changes the encoding nor removes U+FEFF later in the text.

For chunked input, use the same decoder with { stream: true } while more bytes are expected. It retains decoding state and may return an empty string while waiting for the rest of a character. Pass the last chunk without stream: true, or finish with an argument-free decode() to flush. An incomplete trailing sequence becomes a decoding error at that point. The next independent input starts with fresh state.

TextDecoder is part of the web Encoding API, not an ECMAScript 2024 built-in. Check availability in your target runtime.

Examples

{
  const bytes = Uint8Array.of(0xEF, 0xBB, 0xBF, 0x41);
  const standard = new TextDecoder();
  const keep = new TextDecoder("utf-8", { ignoreBOM: true });
  const strict = new TextDecoder("utf-8", { fatal: true });

  console.log(`default BOM: ${standard.decode(bytes).codePointAt(0)}`);
  console.log(`keep BOM: ${keep.decode(bytes).codePointAt(0)}`);
  console.log(`replacement: ${standard.decode(Uint8Array.of(0xFF)).codePointAt(0)}`);

  const before = strict.decode(Uint8Array.of(0xE2, 0x82), { stream: true });
  const after = strict.decode(Uint8Array.of(0xAC));
  console.log(`split: ${before.length}, ${after.codePointAt(0)}`);

  strict.decode(Uint8Array.of(0xE2), { stream: true });
  try {
    strict.decode();
  } catch (error) {
    console.log(`truncated: ${error.name}`);
  }
}

Result

default BOM: 65
keep BOM: 65279
replacement: 65533
split: 0, 8364
truncated: TypeError

The first three lines show decimal code points for `A`, the preserved BOM, and the replacement character. The `split` line shows an empty first result and the code point for `€`; the truncated sequence in strict mode throws `TypeError` only on the final `decode()`.

Related lessons

  • JavaScript · Lesson 3 · Advanced · Version: 4

Sources