Window.btoa() — Methode · JavaScript-Referenz

Signatur

Window.btoa(stringToEncode)

Beschreibung

btoa() („binary to ASCII“) wandelt einen Binärstring in eine Base64-Zeichenkette um. Ein Binärstring ist ein gewöhnlicher JavaScript-String, bei dem jedes Zeichen genau ein Byte darstellt, also einen Codepunkt zwischen 0 und 255 hat. Das Gegenstück ist atob(), das Base64 wieder in einen Binärstring zurückwandelt.

Typische Einsatzfälle sind Data-URLs (data:image/svg+xml;base64,…), der HTTP-Basic-Auth-Header, das Einbetten kleiner Binärdaten in JSON sowie das Kodieren von Daten, die über rein textbasierte Kanäle übertragen werden müssen.

Wichtig: btoa() kann keinen beliebigen Unicode-Text verarbeiten. Enthält der String ein Zeichen oberhalb von U+00FF (z. B. „€“, Emojis oder viele nicht-lateinische Schriftzeichen), wird eine DOMException vom Typ InvalidCharacterError geworfen. Unicode-Text muss daher vorher, z. B. mit TextEncoder, in UTF-8-Bytes umgewandelt und dann in einen Binärstring überführt werden.

Die Methode steht als globale Funktion zur Verfügung, man ruft sie also meist einfach als btoa(…) statt als window.btoa(…) auf. Das funktioniert auch in Web Workers (WorkerGlobalScope).

Parameter

Name	Typ	Default	Beschreibung
$stringToEncode Pflicht	string		Der zu kodierende Binärstring. Jedes Zeichen muss einen Codepunkt von `0` bis `255` haben. Andere Werte werden vorher in einen String umgewandelt (z. B. `btoa(123)` kodiert `"123"`).

Rückgabewert

Typ

string

Beschreibung

Eine ASCII-Zeichenkette mit der Base64-Darstellung von stringToEncode, bei Bedarf mit = auf ein Vielfaches von 4 Zeichen aufgefüllt. Wirft eine DOMException (InvalidCharacterError), wenn der String Zeichen oberhalb von U+00FF enthält.

Beispiele

Einfache ASCII-Zeichenkette kodieren und dekodieren

const encoded = btoa('Hallo Welt');
console.log(encoded);
console.log(atob(encoded));

SGFsbG8gV2VsdA== Hallo Welt

HTTP-Basic-Auth-Header für fetch erzeugen

const user = 'admin';
const password = 'geheim123';

const response = await fetch('/api/intern', {
  headers: {
    Authorization: `Basic ${btoa(`${user}:${password}`)}`
  }
});
console.log(`Basic ${btoa(`${user}:${password}`)}`);

Basic YWRtaW46Z2VoZWltMTIz

Unicode-Text sicher kodieren (UTF-8 über TextEncoder)

const toBase64 = (text) => {
  const bytes = new TextEncoder().encode(text);
  const binary = Array.from(bytes, (b) => String.fromCharCode(b)).join('');
  return btoa(binary);
};

const fromBase64 = (base64) => {
  const binary = atob(base64);
  const bytes = Uint8Array.from(binary, (c) => c.charCodeAt(0));
  return new TextDecoder().decode(bytes);
};

try {
  btoa('Preis: 5 €');
} catch (err) {
  console.log(err.name);
}

const b64 = toBase64('Preis: 5 €');
console.log(b64);
console.log(fromBase64(b64));

InvalidCharacterError UHJlaXM6IDUg4oKs Preis: 5 €

Inline-SVG als Data-URL einsetzen

const svg = '<svg xmlns="http://www.w3.org/2000/svg" width="20" height="20"><circle cx="10" cy="10" r="8" fill="tomato"/></svg>';
const img = document.createElement('img');
img.src = `data:image/svg+xml;base64,${btoa(svg)}`;
document.body.append(img);
console.log(img.src.slice(0, 40));

data:image/svg+xml;base64,PHN2ZyB4bWxucz

// Wichtig · Fallstricke

Nur Latin-1: Zeichen oberhalb von U+00FF lösen einen InvalidCharacterError aus. Für Unicode-Text vorher mit TextEncoder in UTF-8 umwandeln (siehe Beispiel). Der alte Trick btoa(unescape(encodeURIComponent(str))) funktioniert zwar, nutzt aber das veraltete unescape().
Kein Verschlüsseln: Base64 ist eine reine Kodierung und bietet keinerlei Schutz. Basic-Auth-Zugangsdaten daher nur über HTTPS senden.
Kein URL-sicheres Base64: Das Ergebnis enthält +, / und =. Für URLs oder JWTs musst du diese Zeichen selbst ersetzen (+→-, /→_, = entfernen) oder encodeURIComponent() nutzen.
Größe und Leistung: Base64 macht die Daten etwa 33 % größer. Bei großen Binärdaten ist die Umwandlung über Binärstrings langsam und kann mit String.fromCharCode(...bytes) sogar den Stack sprengen. Besser: FileReader.readAsDataURL() oder das neuere Uint8Array.prototype.toBase64() (noch nicht in allen Browsern verfügbar).
Node.js: Ab Node.js 16 global verfügbar, dort aber als Altlast gekennzeichnet. Empfohlen ist Buffer.from(str).toString('base64').
Die Methode wird von allen modernen Browsern seit Langem unterstützt und steht auch in Web Workers bereit.

Siehe auch

Window.atob() new Sanitizer() Window.stop() Window.blur() Window.close()