Developer Guide
Base64 Encoding for Images
Inline small images as data URIs in HTML, CSS, and email. Covers cache tradeoffs, the 33% size bump, CSP img-src data:, and converting files in the browser.
A 1 KB favicon does not deserve its own HTTP round trip. Encoding that file as a data URI lets the browser paint the pixels from the HTML or CSS it already downloaded. The trick is useful for tiny icons, email that cannot fetch remote images, and a single-file HTML page you pass around offline.
It is a poor default for photographs. Base64 expands binary by about 33%, the result is not cached as its own asset, and a 200 KB photo inlined into every page is a gift you keep giving. This guide draws the line between those cases and shows how to convert a file locally on /tools/image-to-base64.
When inlining actually helps
Use a data URI when the image is small, stable, and needed on first paint. Favicons, 16–24 px UI glyphs, a logo in HTML email, and a single-file offline page fit.
Skip inlining once the encoded string is larger than a typical request header budget. A practical cutoff is about 10 KB of original file. Above that, a normal <img src="/icon.png"> is smaller on the wire after gzip, can be cached, and can fail independently of the document.
- Good: icons, spacers, and 1×1 tracking pixels you actually own.
- Good: HTML email and single-file offline pages.
- Bad: hero images, product photos, and anything that changes often.
CSS url() versus an img src
The same data URI works in both places. In markup you set src on an <img> (or srcset if you insist, though srcset plus a huge data URI is usually a mistake). In CSS you wrap it in url():
background-image: url("data:image/gif;base64,R0lGODlhAQABAIAAAAAAAP///yH5BAEAAAAALAAAAAABAAEAAAIBRAA7");
CSS inlining ships the image with the stylesheet. That helps a sprite-sized background that every page needs. It hurts if the stylesheet is shared and the image is unique to one view — every other page still downloads those bytes. Prefer <img> when the picture is content; prefer CSS url() when it is decoration that belongs with the theme.
The 33% overhead and the cache you lose
Base64 maps every three bytes to four ASCII characters. A 6 KB PNG becomes about 8 KB of text, plus the data:image/png;base64, prefix.
A separate image URL can be cached, served from a CDN, and skipped on later pages. An inline URI is part of the HTML or CSS checksum. Change one icon and the whole document cache misses. That is why inlining a 40 KB logo in a layout template is a cost that repeats.
Content-Security-Policy and data: images
If the page sends Content-Security-Policy, img-src must allow data: or the browser will refuse to paint the URI. A policy such as img-src 'self' blocks data:image/... even when the HTML is first-party. Add data: explicitly: img-src 'self' data:.
The same applies to CSS backgrounds under img-src. Do not add data: to script-src; you only need it on the directive that loads images.
Convert a file in the browser
Drop a PNG, JPEG, GIF, WebP, or SVG on /tools/image-to-base64. The dropzone caps files at 5 MB. FileReader.readAsDataURL runs in your tab and emits a full data URI such as data:image/png;base64,…. Nothing is uploaded.
To preview a URI you already have, paste it into /tools/base64-to-image. That page requires the data:image/TYPE;base64, prefix and will not guess a MIME type from raw Base64. Use /tools/base64 for Unicode text that is not an image.
Common pitfalls
The reverse converter is the one people trip on. Copying only the payload (iVBORw0KGgo…) into /tools/base64-to-image fails; prepend data:image/png;base64, (or jpeg, gif, webp, svg+xml) including the comma. The encoder already emits that prefix — keep it.
Do not treat Base64 as compression: the file gets larger, not smaller. Quote CSS url() values that contain + and /.
/tools/base64-to-imagedoes not auto-detect raw Base64.- Dropzone limit on
/tools/image-to-base64is 5 MB. - CSP
img-src 'self'blocks data URIs until you adddata:.
Worked examples
1×1 GIF as a data URI
Standard 1×1 transparent GIF bytesdata:image/gif;base64,R0lGODlhAQABAIAAAAAAAP///yH5BAEAAAAALAAAAAABAAEAAAIBRAA7This is the widely used 1×1 GIF. Paste it into an <img src> or a CSS url() as-is.
HTML versus CSS
<img src="data:image/gif;base64,R0lGODlhAQABAIAAAAAAAP///yH5BAEAAAAALAAAAAABAAEAAAIBRAA7" width="1" height="1" alt="" />
.icon {
background-image: url("data:image/gif;base64,R0lGODlhAQABAIAAAAAAAP///yH5BAEAAAAALAAAAAABAAEAAAIBRAA7");
}Same payload, two contexts. The CSS form needs quotes because of the characters in Base64.
Frequently asked questions
Should I Base64 every image on a page?
No. Inline only tiny, first-paint assets. Anything over about 10 KB is usually better as a normal URL so it can be cached and loaded in parallel.
Why is the data URI longer than the file?
Base64 uses 4 characters for every 3 bytes, so the payload grows by about 33%. The data:image/TYPE;base64, prefix adds a few dozen more characters.
Can I paste raw Base64 into Base64 to Image?
Not on /tools/base64-to-image. That tool requires data:image/TYPE;base64, and does not sniff magic bytes. Keep the prefix the encoder produced.
Do data URIs work in email?
Some clients render them; many still prefer CID attachments. Keep the files tiny either way. See the email guide if you are building MIME rather than a web page.
Is any of this uploaded?
No. /tools/image-to-base64 and /tools/base64-to-image run FileReader and image decoding in the browser. There is no image API on thedevtools.in.
Summary
Inline a data URI when the image is small and the extra request would cost more than the 33% size bump. Convert the file on /tools/image-to-base64, keep the data:image/TYPE;base64, prefix if you round-trip through /tools/base64-to-image, and add data: to img-src when CSP is in play. Leave photographs on their own URLs.