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.ignoreBOMIn 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