Base64 turns binary data into text. It does not encrypt, compress or obscure; it changes the alphabet so bytes can travel through channels that only accept certain characters. Understanding three details — the alphabet, padding, and the UTF-8 step — prevents most of the bugs people attribute to “Base64 being weird”.

The mechanics

Base64 reads three bytes at a time (24 bits) and writes four characters (6 bits each). The 64-character alphabet is A–Z, a–z, 0–9, + and /. Because three bytes become four characters, the encoded size is about 33% larger.

bytes:    01001000 01100101 01101100   (H e l)
6-bit:    010010 000110 010101 101100
chars:    S      G      V      s

If the input length is not a multiple of three, the final group is padded with =. One = means two bytes in the last group; == means one byte.

SGVsbG8=      "Hello" (5 bytes -> 8 chars, one =)
SGVsbG8h      "Hello!" (6 bytes -> 8 chars, no padding)

The UTF-8 step

JavaScript's btoa operates on Latin-1 code units. It throws InvalidCharacterError for characters outside that range, which includes Chinese, Japanese, Arabic and emoji. The fix is to convert the string to UTF-8 bytes first:

function toBase64(text) {
  const bytes = new TextEncoder().encode(text);
  let binary = "";
  for (const byte of bytes) binary += String.fromCharCode(byte);
  return btoa(binary);
}

Decoding reverses the process: atob, then map each character back to a byte, then TextDecoder. Skipping the byte conversion produces mojibake that looks like a different encoding problem.

URL-safe Base64

Standard Base64 uses + and /. In a URL, + is interpreted as a space in query strings, and / is a path separator. The URL-safe variant (base64url, RFC 4648) replaces them with - and _, and usually omits padding. JWT segments use this form.

The two alphabets are not interchangeable. A strict decoder for one may reject the other. If a JWT segment fails to decode, check for - and _ and add padding before using a standard decoder.

When to use it

  • Embedding small images as data URIs.
  • Sending binary data in JSON.
  • Encoding credentials in the Authorization: Basic header.
  • Storing opaque blobs in text-only systems.
  • JWT header, payload and signature segments.

When not to use it

  • As encryption. It is reversible by anyone.
  • As compression. It makes data larger.
  • For large images in HTML. The 33% overhead and loss of separate caching usually outweigh the saved request.
  • As a password hash. It is not a hash and provides no work factor.

Common errors

Symptom Cause
btoa throws Non-Latin-1 characters; encode UTF-8 first
Decoded text is garbled Wrong source encoding or double encoding
Invalid character error Whitespace inside the string, or URL-safe alphabet passed to a standard decoder
Output ends with = unexpectedly Input length not a multiple of three; padding is normal
JWT segment fails Missing padding or wrong alphabet

Security note

Base64 hides nothing. A decoded payload may contain a script, a command or credentials. Treat unknown Base64 as untrusted input, do not execute it, and do not assume it is safe because it looks like random text.

The Base64 encoder handles UTF-8 correctly, and the decoder normalizes whitespace, padding and URL-safe characters. For JWT-style output, use the URL-safe encoder.