Five Ways Inlined Base64 Breaks
Inlining Base64 fails in five predictable places: the payload is a third larger than the file it replaces and stops being cacheable; the declared MIME type overrides the real bytes; line breaks and stripped padding break the decode; atob mangles anything that is not Latin-1; and a Content-Security-Policy without data: blocks the resource silently. Each has a one-line check.
- Base64 is 33 percent larger and cannot be cached separately from the file that carries it
- Browsers trust the MIME type in the data URI — not the bytes behind it
- Whitespace inside the string and missing
=padding both throw btoathrows on any character above U+00FF;atobreturns mojibake for UTF-8- CSP needs
img-src data:orfont-src data:— otherwise it fails with no error
Processed as you paste — no button to press (Ctrl+Enter converts now / Esc clears)
Drop a file here, or — Ctrl+V a screenshot works too
Any file type · 100 MB maximum
Paste, drag and drop, or Ctrl+V a screenshot
1. The 33 percent tax, and the cache you lose
Four Base64 characters carry three bytes, so every inlined asset is about a third larger than the file. That alone is survivable. The real cost is that the payload now lives inside your CSS or HTML: it is re-sent whenever that file is not cached, it cannot be cached on its own, and it blocks the document behind it.
A 30 KB font inlined in the main stylesheet turns a 40 KB CSS file into an 80 KB one that must arrive in full before anything renders. The same font as a separate file downloads in parallel and is cached for a year.
Check: compare gzipped transfer size of "CSS with the asset inlined" against "CSS + separate file" in DevTools → Network, with cache disabled. Below roughly 2–3 KB the inline wins; above 10 KB it almost never does.
2. The declared MIME type overrides the real bytes
A data URI states its type: data:image/png;base64,.... The browser believes that label. Encode a WebP, label it PNG, and Chrome renders nothing — with no console error, because as far as the parser is concerned the image is simply corrupt.
Fonts are worse, because the failure is silent in a different way: a TrueType file served as font/woff2 may load in one browser and be rejected in another.
Check: read the first bytes before trusting the label — 89 50 4E 47 is PNG, RIFF….WEBP is WebP, wOF2 is WOFF2, 00 01 00 00 is raw TrueType. The decoder here does exactly that check and names the format it finds.
3. Whitespace and stripped padding
Base64 that has travelled through email, a YAML file or a chat window often carries line breaks every 76 characters. atob throws on those. The same string with newlines removed may then fail because padding was stripped to save two bytes, and the length is no longer a multiple of four.
const clean = value.replace(/^data:[^;]+;base64,/, '').replace(/\s+/g, '');
const standard = clean.replace(/-/g, '+').replace(/_/g, '/');
const padded = standard + '='.repeat((4 - (standard.length % 4)) % 4);
Check: strip whitespace, normalise the URL-safe alphabet, restore padding — in that order. If it still throws, the string was truncated in transit; a length that is not a multiple of four after cleaning is the tell.
4. UTF-8: btoa throws, atob mangles
btoa accepts only characters U+0000–U+00FF. Pass it anything with an accent, an emoji or a Chinese character and it throws InvalidCharacterError. Go the other way and atob happily returns a "string" that is really raw bytes, so é and 中文 arrive as mojibake.
// encode
const bytes = new TextEncoder().encode(text);
const b64 = btoa(String.fromCharCode(...bytes)); // loop for large input
// decode
const out = new TextDecoder('utf-8').decode(
Uint8Array.from(atob(b64), (c) => c.charCodeAt(0))
);
Check: round-trip a string containing an emoji and a CJK character. If either comes back changed, the code is treating bytes as Latin-1 text.
5. Content-Security-Policy blocks it silently
A policy written as img-src 'self' blocks every data: image, and font-src 'self' blocks inlined fonts. The browser reports a CSP violation in the console and renders nothing else — which is easy to miss in a build where the CSS came from a bundler and nobody wrote a data URI by hand.
Check: open the console and filter for "Refused to load". If your build step inlines assets, the policy needs data: in img-src, font-src and sometimes style-src.
The checklist before you inline anything
- Under 3 KB and used once on the page? Inline it.
- Over 10 KB, or reused across pages? Serve it as a file with a cache header.
- Does the declared MIME type match the first bytes? Verify, do not assume.
- Did the string survive transport? Strip whitespace, restore padding, check
length % 4. - Does any text pass through
atob/btoa? UseTextEncoder/TextDecoder. - Does the CSP allow
data:for that resource type? - Is the asset a font? Check the licence before embedding it at all.
Frequently asked questions
Is inlining Base64 ever faster?
Yes, for small assets used immediately above the fold, where removing one request matters more than the extra bytes. The break-even is usually between 2 and 4 KB gzipped; measure it rather than guessing.
Why does my image data URI render as a broken icon?
Usually a MIME mismatch or a truncated string. Check the first bytes and the length — both are covered by the general decoder.
Does a data URI affect SEO?
Indirectly. It increases HTML size and blocks rendering, both of which show up in Core Web Vitals. Search engines have no problem reading data URIs, but they cannot index an inlined image as its own asset.