TextEncoder

new TextEncoder()

TextEncoder is part of the Encoding API and converts JavaScript strings into UTF-8 encoded byte data. It lives on window in browsers and on the util module in Node.js. Every modern environment supports it.

Constructor

const encoder = new TextEncoder();

Creates a new TextEncoder instance. The constructor takes no arguments.

encoding

encoder.encoding  // "utf-8"

The encoding property is read-only and always returns the string "utf-8". TextEncoder only supports UTF-8. There is no way to request any other encoding, and the property exists so you can confirm what you’re dealing with.

encode()

encode(input)

Parameters

• input (string) — The text to encode.

Returns Uint8Array — A new Uint8Array containing the UTF-8 encoded bytes.

const encoder = new TextEncoder();
const bytes = encoder.encode("Hello, 世界");

console.log(bytes.length); // 13
console.log(bytes); // Uint8Array(13) [ 72, 101, 108, 108, 111, 44, 32, 228, 184, 150, 231, 149, 140 ]

Each character in the input string becomes one or more bytes. ASCII characters stay single-byte, while characters outside the ASCII range (like 世 and 界) use two to four bytes each.

encodeInto()

encodeInto(input, destination)

Encodes a string directly into a pre-allocated Uint8Array. This avoids allocating a new array on every call, which matters in tight loops or high-frequency encoding.

Parameters

• input (string) — The text to encode.
• destination (Uint8Array) — The buffer to write encoded bytes into. Must have enough space.

Returns { read: number, written: number } — An object telling you how many input characters were consumed and how many output bytes were written.

const encoder = new TextEncoder();
const buffer = new Uint8Array(10);
const result = encoder.encodeInto("Hello", buffer);

console.log(result.read);    // 5
console.log(result.written); // 5

The truncation gotcha

encodeInto() does not throw when the destination buffer is too small. It silently stops after filling the buffer. The return value tells you what happened:

const encoder = new TextEncoder();
const small = new Uint8Array(3);
const result = encoder.encodeInto("Hello", small);

console.log(result.read);    // 2  — only "He" fit in 3 bytes
console.log(result.written); // 3  — buffer is full

// "llo" was not encoded. You must handle the remainder yourself.
if (result.read < "Hello".length) {
    // remaining characters need a larger buffer
}

This catches developers who assume encodeInto() encodes everything. Always check result.read against the input length.

Pre-allocating for performance

// Slow: new Uint8Array every call
for (const line of lines) {
    const bytes = encoder.encode(line); // allocation each iteration
}

// Faster: reuse a buffer and grow only when needed
const buf = new Uint8Array(1024);
for (const line of lines) {
    const result = encoder.encodeInto(line, buf);
    processBytes(buf.slice(0, result.written));
    // If result.written === buf.length, buf was too small — grow it
}

TextEncoderStream

For streaming encoding with the Streams API, use TextEncoderStream:

const textEncoder = new TextEncoderStream();
const readable = textEncoder.readable;
const writable = textEncoder.writable;

const writer = writable.getWriter();
writer.write("some text");
writer.close();

// Or pipe a ReadableStream through the TextEncoderStream
const inputStream = new ReadableStream({ /* ... */ });
const outputStream = inputStream.pipeThrough(new TextEncoderStream());

TextEncoderStream has the same encoding, encode(), and encodeInto() as TextEncoder, but as a stream transform. It is useful when building text-processing pipelines with the Streams API.

Node.js notes

Node.js 11.0.0+ ships with util.TextEncoder globally. In older versions, you had to require it explicitly:

// Node 11+
const { TextEncoder } = require('util');
const encoder = new TextEncoder();

Node’s Buffer and Uint8Array share memory, so you can pass a Buffer as the destination in encodeInto() without copying.

Examples

Encoding for binary storage

const encoder = new TextEncoder();
const data = JSON.stringify({ name: "张三", score: 99 });
const bytes = encoder.encode(data);

// bytes is a Uint8Array — ready to store in IndexedDB, send over WebSocket, etc.

Incremental encoding with encodeInto()

const encoder = new TextEncoder();
const chunkSize = 256;
let offset = 0;

function encodeChunk(text) {
    const remaining = text.length - offset;
    const buf = new Uint8Array(Math.min(chunkSize, remaining));
    const result = encoder.encodeInto(text.slice(offset), buf);

    offset += result.read;
    return { bytes: buf.slice(0, result.written), done: result.read === remaining };
}

See Also

• ArrayBuffer — The buffer type that holds raw binary data
• TypedArray — The typed array type returned by encode()

Written

• File: sites/jsguides/src/content/reference/built-in-objects/textencoder.md
• Words: ~790
• Read time: 4 min
• Topics covered: TextEncoder constructor, encoding property, encode(), encodeInto(), TextEncoderStream, Node.js, gotchas
• Verified via: https://developer.mozilla.org/en-US/docs/Web/API/TextEncoder
• Unverified items: none