Uint8Array.prototype.toBase64()

Limited availability

This feature is not Baseline because it does not work in some of the most widely-used browsers.

The toBase64() method of Uint8Array instances returns a base64-encoded string based on the data in this Uint8Array object.

This method should be preferred over Window.btoa(), especially if you already have a Uint8Array holding the object, because you don't need to convert it to a string first.

Syntax

toBase64()
toBase64(options)

Parameters

options Optional

An object customizing the base64 string format. It can contain the following properties:

alphabet Optional

A string specifying the base64 alphabet to use. It can be one of the following:

"base64" (default): Encode input with the standard base64 alphabet, which uses + and /.
"base64url": Encode input with the URL-safe base64 alphabet, which uses - and _.

omitPadding Optional

A boolean specifying whether to omit padding characters (=) at the end of the base64 string. The default is false.

Return value

A base64-encoded string representing the data in the Uint8Array.

Exceptions

TypeError

Thrown in one of the following cases:

The options object is not an object or undefined.
The options.alphabet is not of the expected values or undefined.

Examples

Encoding binary data

This example uses the default alphabet and omitPadding options to encode data from a Uint8Array into a base64 string.

const uint8Array = new Uint8Array([29, 233, 101, 161]);
console.log(uint8Array.toBase64()); // "HelloQ=="

Encoding data without padding

const uint8Array = new Uint8Array([29, 233, 101, 161]);
console.log(uint8Array.toBase64({ omitPadding: true })); // "HelloQ"

Encoding data with URL-safe alphabet

This example populates a URLSearchParams object with a base64-encoded string using the URL-safe alphabet.

const uint8Array = new Uint8Array([46, 139, 222, 255, 42, 46]);
const base64 = uint8Array.toBase64({ alphabet: "base64url" });
const params = new URLSearchParams();
params.set("data", base64);
console.log(params.toString()); // "data=Love_you"

Stream encoding

This example is adapted from the original proposal, showcasing how to implement streaming in userland. It mimics the TextEncoder API with the stream option.

class Base64Encoder {
  #extra;
  #extraLength;
  constructor() {
    this.#extra = new Uint8Array(3);
    this.#extraLength = 0;
  }

  // Partly derived from https://github.com/lucacasonato/base64_streams/blob/main/src/iterator/encoder.ts
  encode(chunk = Uint8Array.of(), options = {}) {
    const stream = options.stream ?? false;

    if (this.#extraLength > 0) {
      const bytesNeeded = 3 - this.#extraLength;
      const bytesAvailable = Math.min(bytesNeeded, chunk.length);
      this.#extra.set(chunk.subarray(0, bytesAvailable), this.#extraLength);
      chunk = chunk.subarray(bytesAvailable);
      this.#extraLength += bytesAvailable;
    }

    if (!stream) {
      // assert: this.#extraLength.length === 0 || this.#extraLength === 3 || chunk.length === 0
      const prefix = this.#extra.subarray(0, this.#extraLength).toBase64();
      this.#extraLength = 0;
      return prefix + chunk.toBase64();
    }

    let extraReturn = "";

    if (this.#extraLength === 3) {
      extraReturn = this.#extra.toBase64();
      this.#extraLength = 0;
    }

    const remainder = chunk.length % 3;
    if (remainder > 0) {
      this.#extra.set(chunk.subarray(chunk.length - remainder));
      this.#extraLength = remainder;
      chunk = chunk.subarray(0, chunk.length - remainder);
    }

    return extraReturn + chunk.toBase64();
  }
}

const encoder = new Base64Encoder();

console.log(
  encoder.encode(Uint8Array.of(72, 101, 108, 108, 111), { stream: true }),
);
// "SGVs"
console.log(
  encoder.encode(Uint8Array.of(32, 87, 111, 114, 108, 100), { stream: true }),
);
// "bG8gV29y"
console.log(encoder.encode());
// "bGQ="

Specifications

Specification
Uint8Array to/from base64 # sec-uint8array.prototype.tobase64

Browser compatibility

	Desktop					Mobile						Server
	Chrome	Edge	Firefox	Opera	Safari	Chrome Android	Firefox for Android	Opera Android	Safari on IOS	Samsung Internet	WebView Android	Deno	Node.js
`toBase64`	No	No	133	No	18.2	No	133	No	18.2	No	No	No	No