Base64 Encode and Decode

The encoder takes the input three bytes (24 bits) at a time and splits those 24 bits into four 6-bit groups. Each group is a number from 0 to 63, which indexes into the alphabet A–Z, a–z, 0–9, +, /. Here is the classic example, the ASCII string Man:

So Man encodes to TWFu. When the input length is not a multiple of three, the last group is padded with zero bits and the output is filled out with = so it is still a multiple of four characters: Ma becomes TWE= and M becomes TQ==. One = means the final group held two bytes, two mean it held one.

Because every 3 bytes turn into 4 characters, Base64 output is about 33% larger than the input (4/3 of the size, rounded up to a whole group). MIME email adds a line break every 76 characters on top of that, which is what the Wrap at 76 option produces.

Standard Base64 is defined in RFC 4648 section 4. Its + and / characters cause trouble in URLs and file names: + is read as a space in query strings and / is a path separator. Section 5 defines the "URL and filename safe" alphabet, which swaps them for - and _. Padding is often dropped as well, since the decoder can work out the length.

Most "invalid Base64" errors in practice come from feeding one variant to a decoder that only accepts the other. This decoder accepts both and adds missing padding. If you need to put standard Base64 into a query string, either switch to Base64URL or percent-encode it with the URL encoder.

• Data URIs: <img src="data:image/png;base64,iVBORw0KGgo..."> inlines a small image into HTML or CSS. Use the data: URI output with Encode file to produce one.
• HTTP Basic auth: Authorization: Basic dXNlcjpwYXNz is just user:pass encoded, as described in RFC 7617.
• Email attachments: MIME (RFC 2045) sends binary attachments as Base64 wrapped at 76 characters per line.
• JWTs: each of the three dot-separated parts is Base64URL without padding. Paste a whole token into the JWT decoder to see the header and claims.

Base64 has no key and no secret. Anyone who sees dXNlcjpwYXNz can decode it in a second, which is why Basic auth is only acceptable over HTTPS and why a Base64 value in a Kubernetes secret is not protected by the encoding. If you need to check that data was not changed, use a hash from the hash generator; if you need to hide it, use real encryption.

The browser's built-in btoa() works on "binary strings", where each character must be in the range 0–255. Pass it anything outside Latin-1 and it throws:

btoa('✓ done');
// Chrome: InvalidCharacterError: Failed to execute 'btoa' on 'Window':
//   The string to be encoded contains characters outside of the Latin1 range.

The opposite mistake is quieter. atob() returns one character per byte, so decoding UTF-8 text with it turns é (bytes C3 A9, Base64 w6k=) into the mojibake é. The fix in both directions is to convert between strings and UTF-8 bytes explicitly:

function utf8ToBase64(str) {
  const bytes = new TextEncoder().encode(str);
  let binary = '';
  for (const b of bytes) binary += String.fromCharCode(b);
  return btoa(binary);
}

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

Newer browsers also ship Uint8Array.prototype.toBase64() and Uint8Array.fromBase64(), which handle the alphabet and padding for you; check MDN for support before relying on them. In Node.js, Buffer.from(str).toString('base64') and Buffer.from(b64, 'base64').toString('utf8') already use UTF-8.