← Guides

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.

base64 imagedata uriembed image in htmlinline image cssbase64 image encoder

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-image does not auto-detect raw Base64.
  • Dropzone limit on /tools/image-to-base64 is 5 MB.
  • CSP img-src 'self' blocks data URIs until you add data:.

Worked examples

1×1 GIF as a data URI

Input
Standard 1×1 transparent GIF bytes
Output
data:image/gif;base64,R0lGODlhAQABAIAAAAAAAP///yH5BAEAAAAALAAAAAABAAEAAAIBRAA7

This 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.

Try it yourself

Put what you've learned into practice with our free browser-native tool.

Open Tool →