Uint8Array.prototype.toBase64()
Baseline
2025
Newly available
Since September 2025, this feature works across the latest devices and browser versions. This feature might not work in older devices or 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
optionsOptional-
An object customizing the base64 string format. It can contain the following properties:
alphabetOptional-
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_.
omitPaddingOptional-
A boolean specifying whether to omit padding characters (
=) at the end of the base64 string. The default isfalse.
Return value
A base64-encoded string representing the data in the Uint8Array.
Exceptions
TypeError-
Thrown in one of the following cases:
- The
optionsobject is not an object orundefined. - The
options.alphabetis not of the expected values orundefined.
- The
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
Loading…