Base64 shows up everywhere once you start looking: email attachments, data: URLs in CSS, the three parts of a JSON Web Token, HTTP Basic authentication headers, Kubernetes secrets, and API fields that carry files inside JSON. It exists to solve one problem: moving arbitrary binary data through systems that only handle text safely.
This guide explains how the encoding works at the byte level, why the output is always about a third larger, how the URL-safe variant differs, when embedding images as Base64 data URIs helps performance and when it hurts, and the mistakes that cause most Base64 bugs, including the one that makes btoa() throw on non-English text.
How Base64 works
Base64 takes input three bytes (24 bits) at a time and splits those bits into four groups of six. Each six-bit value, from 0 to 63, is replaced by one character from a fixed alphabet: A to Z, a to z, 0 to 9, then + and /. Every character in that alphabet is printable ASCII and passes unchanged through email, JSON, XML and HTTP headers.
When the input length is not a multiple of three, the last group is short. The encoder fills the missing bits with zeros and adds = padding so the output length is always a multiple of four: one = means the last group had two bytes, == means it had one.
Text: M a n
Bytes: 77 97 110
Bits: 01001101 01100001 01101110
6-bit: 010011 010110 000101 101110
Values: 19 22 5 46
Base64: T W F u -> "TWFu"
"Ma" -> "TWE=" "M" -> "TQ=="The 33% size overhead
Four output characters for every three input bytes means Base64 is 4/3 the size of the original, plus up to two padding characters. A 30 KB image becomes about 40 KB of text. Some encoders, such as the MIME encoding used in email, also insert a line break every 76 characters, adding a little more.
That overhead is the price of text safety, and it matters at scale. Sending files as Base64 inside JSON increases bandwidth, memory use and parsing time compared with a multipart upload or a direct binary transfer. For files larger than a few hundred kilobytes, prefer a binary upload or a pre-signed URL and pass only the reference in JSON.
Base64 vs Base64URL
Standard Base64 uses + and /, which have special meanings in URLs and file names. Base64URL, defined in RFC 4648, replaces them with - and _ and usually omits the = padding. JSON Web Tokens, many OAuth parameters and some API identifiers use Base64URL.
Mixing the two is a common bug. A standard decoder rejects - and _, and a Base64URL string without padding may fail in decoders that insist on a length divisible by four. To decode a JWT segment with a standard decoder, swap - for + and _ for /, then add = until the length is a multiple of four.
// Base64URL to standard Base64 (JavaScript)
function fromBase64Url(s) {
s = s.replace(/-/g, '+').replace(/_/g, '/');
while (s.length % 4) s += '=';
return s;
}Data URIs: when inlining images helps and when it hurts
A data URI puts a whole file inside a URL: data:image/png;base64, followed by the encoded bytes. It can be used anywhere a URL can, including img src attributes and CSS url() values, and the browser does not make a separate request for it.
Inlining helps for very small images, roughly under a couple of kilobytes, such as icons, tiny placeholders and single-file HTML documents or emails. It hurts for anything larger. The image grows by a third, cannot be cached separately from the HTML or CSS that contains it, is downloaded again whenever that file changes, and blocks rendering when placed in a render-critical stylesheet. With HTTP/2 and HTTP/3, extra requests are cheap, so the old argument for inlining to save requests is much weaker than it used to be.
For SVG, consider a URL-encoded data URI (data:image/svg+xml,...) instead of Base64: SVG is already text, and URL encoding is usually smaller and still compresses well with gzip.
Base64 is not encryption
Base64 is an encoding, not a security measure. Anyone can decode it instantly, with no key. Credentials sent with HTTP Basic auth are only Base64-encoded, which is why Basic auth must only ever be used over HTTPS. Kubernetes Secrets are Base64-encoded in their manifests, not encrypted; protecting them needs encryption at rest and access controls.
The same applies in reverse. If you find a Base64 string in a config file, log or repository, assume anyone who can see it can read it. Do not commit encoded secrets to source control; use a secret manager. JWT payloads are also readable by anyone, so never put sensitive data in a token payload unless the token is encrypted (JWE), not just signed.
Common pitfalls and the btoa UTF-8 trap
Base64 encodes bytes, not characters, so text has to become bytes first, and the character encoding you choose changes the result. In browsers, btoa() only accepts characters in the Latin-1 range and throws "InvalidCharacterError" on text such as "₹100" or emoji. Encode the text to UTF-8 bytes first, as below.
- Line breaks and spaces: MIME and PEM data wrap lines at 64 or 76 characters. Most decoders skip whitespace, but strict ones fail; strip it first.
- Double encoding: encoding a string that is already Base64 produces valid but useless output. If decoding gives you something that still looks like Base64, it was encoded twice.
- Data URI prefixes: remove "data:image/png;base64," before passing the string to a plain Base64 decoder.
- Binary as text: decoding image or PDF data and printing it as a string produces garbage characters. Decode binary to bytes or a Blob, not to text.
// UTF-8-safe Base64 in the browser
const bytes = new TextEncoder().encode('Price: ₹100 ✓');
const b64 = btoa(String.fromCharCode(...bytes));
const decoded = new TextDecoder().decode(
Uint8Array.from(atob(b64), (c) => c.charCodeAt(0)),
);
// Node.js
Buffer.from('Price: ₹100 ✓', 'utf8').toString('base64');Working with Base64 day to day
For text, the Neemtools Base64 Encoder and Base64 Decoder handle UTF-8 correctly, so non-English text and emoji round-trip without the btoa error, and the decoder ignores line breaks in wrapped input. For images, Image to Base64 produces a ready-to-paste data URL and Base64 to Image turns a string from an API response or stylesheet back into a file you can view. All four run in your browser, which matters because Base64 strings are often credentials or internal data.
Before inlining an image, compress and resize it first. Base64 makes every byte a third larger, so a smaller source image is the only way to get a shorter string.