Base64 Encoder/Decoder

Where Base64 Encoding Is Used

Base64 was invented to solve a specific problem: how do you transmit binary data over channels designed for 7-bit ASCII text? Email was the original use case. The MIME standard (RFC 2045) uses Base64 as one of its content transfer encodings so that attachments — images, PDFs, executables — can travel through mail servers that only handle printable ASCII without corrupting the bytes. This remains the basis of how email attachments work today.

Data URIs in HTML and CSS use Base64 to embed images, fonts, or small scripts directly in markup: `<img src="data:image/png;base64,iVBORw0KGgo...">`. This eliminates an HTTP request for small assets but at the cost of a 33% size increase and no browser caching. JWT tokens use Base64URL encoding (a variant defined in RFC 4648 §5 that replaces `+` with `-` and `/` with `_`) for the header and payload sections so they can be safely embedded in URLs and HTTP headers without percent-encoding.

RFC 4648 formalizes the Base64 alphabet and padding rules that all compliant implementations must follow. The standard defines both the regular alphabet (using `+` and `/`) and the URL-safe variant. Understanding which variant an API expects is important — mixing them up is a common source of authentication failures when working with OAuth tokens or signed URLs.

Base64 in JavaScript

btoa() throws a 'InvalidCharacterError' for any character with a code point above 255 — emojis and non-Latin scripts included. Always use the encodeURIComponent wrapper or Node's Buffer.from() when handling Unicode input.

// Browser built-ins (ASCII/Latin-1 only)
const encoded = btoa("Hello, world!"); // "SGVsbG8sIHdvcmxkIQ=="
const decoded = atob("SGVsbG8sIHdvcmxkIQ=="); // "Hello, world!"

// Unicode-safe encoding in the browser
function encodeUnicode(str) {
  return btoa(
    encodeURIComponent(str).replace(/%([0-9A-F]{2})/g, (_, p1) =>
      String.fromCharCode(parseInt(p1, 16))
    )
  );
}

// Node.js — handles any encoding cleanly
const buf = Buffer.from("Hello, world!", "utf8");
const b64 = buf.toString("base64");           // encode
const back = Buffer.from(b64, "base64").toString("utf8"); // decode

// URL-safe Base64 (RFC 4648 §5) — used in JWTs
const urlSafe = b64.replace(/+/g, "-").replace(///g, "_").replace(/=/g, "");

Common Base64 Mistakes

• Confusing encoding with encryption: Base64 is trivially reversible by anyone — it provides no confidentiality. Never use it to 'hide' passwords or tokens.
• Double-encoding: if you Base64-encode a string that is already Base64-encoded, you get valid but useless output. Always decode first and inspect before re-encoding.
• Ignoring the 33% size overhead: every 3 bytes of input become 4 bytes of Base64. Embedding large images as data URIs in CSS noticeably inflates file sizes and hurts page load time.
• Using standard Base64 where URL-safe is required: the `+` and `/` characters in standard Base64 are special characters in URLs and HTTP headers. JWT libraries and signed-URL systems use the `-` / `_` variant (RFC 4648 §5).
• Forgetting padding: some implementations strip the trailing `=` padding characters. Others require them. When an API returns a Base64 string that fails to decode, try adding `=` characters until the length is a multiple of 4.