How to embed an image in CSS on a Mac
You can do this with B64 and get the whole rule, quoting and all. Here is how, and which assets are worth embedding in a stylesheet.
A stylesheet that references ../img/icon.svg is a stylesheet with a dependency. Move the file, rename the folder, or hand the CSS to someone else, and the reference breaks. Embedding the asset in the rule removes that dependency entirely: the stylesheet carries its own pictures.
This guide covers producing the rule in B64 and choosing what deserves to be embedded.
The conversion runs in the app, on your Mac. Nothing is uploaded and there is no account — so the picture you are embedding does not have to visit a stranger's server on its way into your markup.
Get the rule
Open Encode
Click Encode in the sidebar or press ⌘1.
Load the image
Drag it in or press ⌘O. SVG and PNG are the usual candidates for a stylesheet.
Choose CSS Background
Pick CSS Background from the format menu. You get a complete declaration — property,
url(), quoting, data URI and semicolon.Paste it into your stylesheet
Copy (⇧⌘C) and drop it into the rule that needs it.
background-image: url("data:image/svg+xml;base64,PHN2ZyB4bWxucz0iaHR0…");The quoting matters more than it looks. An unquoted url() has its own rules about which characters need escaping, and a Base64 payload can contain + and /. Quoting the value sidesteps all of it, which is why the output is written that way.
SVG is the best candidate
Encoded SVG in CSS is the combination that pays off most often:
- Icons stay sharp at any size, because they are still vectors.
- They are small, so the 33% overhead is a few kilobytes.
- No escaping to get wrong. Raw SVG markup in a stylesheet has to be escaped by hand, and the rules are fiddly. Base64 output contains none of the characters that cause the trouble.
See how to convert an SVG to Base64 for the details specific to vector files.
What to embed, and what to leave alone
| Asset | Embed? | Why |
|---|---|---|
| An interface icon (SVG, under 5 kB) | Yes | Tiny, never changes, no escaping |
| A small texture or pattern tile | Yes | Repeats, so one copy covers a lot |
| A 1×1 spacer or placeholder | Yes | Absurd to make a network request for |
| A logo used site-wide | Maybe | Fine if small; a linked file caches better across pages |
| A background photograph | No | Blocks the stylesheet, which blocks rendering |
| Anything you expect to change often | No | Re-encoding on every edit, and the diff is unreadable |
A browser will not paint until the CSS has arrived. Every embedded byte is a byte the page waits for. That is a fine trade for a 2 kB icon and a bad one for a 400 kB photograph.
Two things to plan for
Diffs. An embedded asset is a very long single line in version control. Changing it produces a diff nobody can read. Keep embedded assets to things that do not change.
Dark mode. An embedded raster image cannot be recoloured by CSS. If an icon needs to follow the theme, embed two and switch between them, or use a mask-image approach and colour the element instead.
Going the other way
Copy the whole declaration — background-image, url() and all — and paste it into Decode. The payload is found inside and the picture appears. See how to extract an image from a CSS file.
Troubleshooting
The background does not show
Check that the element has a size — a background needs something to paint on. Then check the payload survived intact: paste the data URI part into a browser tab and see whether the picture appears.
My CSS formatter broke the rule
Some formatters wrap long values. A newline inside the data URI invalidates it. Exclude the file, or tell the formatter not to wrap that line.
The stylesheet got very large
Count what you have embedded. Each asset costs its own size plus a third, inside a file the browser waits for before painting.
Frequently asked questions
Do I get the whole background-image rule or just the URL?
The whole declaration, correctly quoted — property, url(), the data URI and the semicolon. Quoting matters because a Base64 payload can contain plus and slash characters that an unquoted url() treats specially.
Which images are worth embedding in CSS?
Small, stable ones: interface icons, pattern tiles, spacers. Avoid photographs and anything you expect to change, since stylesheets are render-blocking and an embedded asset makes a diff nobody can read.
Why is SVG the best fit for this?
It stays sharp at any size, it is tiny, and encoding removes the escaping problem that makes raw SVG markup in CSS so awkward.
Can I recolour an embedded icon with CSS?
Not a raster one. Embed two versions and switch between them, or use mask-image and colour the element instead.