SVG to Data URI in CSS: Encoding Rules

Put an SVG to data URI in CSS correctly: which characters to percent-encode, UTF-8 versus base64, quoting, recoloring with mask-image, and CSP rules.

By SVG to React. Published October 31, 2026. Updated October 31, 2026.

A data URI puts a file directly inside a URL, so an SVG can live in a stylesheet with no separate request. This works well for small decorative images such as list bullets, select arrows, dividers, and simple icons. It also breaks in confusing ways when the SVG is pasted in without encoding. This post covers the syntax, the characters that must be escaped and why, the base64 question, and a pattern for icons that follow the text color.

The syntax

A data URI has the form data:[media type][;base64],data. For SVG the media type is image/svg+xml, and the data can be the SVG markup itself, percent-encoded where needed:

.badge {
  background-image: url("data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 16 16'%3E%3Cpath fill='%230f766e' d='M8 1 1 15h14z'/%3E%3C/svg%3E");
  background-repeat: no-repeat;
  background-size: 1rem 1rem;
}

The SVG must include xmlns="http://www.w3.org/2000/svg". Inline SVG in HTML works without it because the HTML parser puts the element in the SVG namespace. A data URI is parsed as a standalone XML document, and without the namespace the browser does not treat it as SVG at all, so nothing renders. Converters that produce React components often remove xmlns, so do not reuse that output here.

Which characters to encode

The data part is a URL, so characters with a meaning in URLs must be escaped as % followed by two hex digits. Encoding everything with encodeURIComponent works, but it makes the result longer and unreadable. In practice a short list is enough:

• # becomes %23. This is the one that breaks most often. In a URL, # starts the fragment, so current browsers cut the image off at the first hex color.
• % becomes %25. A literal percent sign, such as width="100%", would otherwise be read as the start of an escape.
• < and > become %3C and %3E. Most browsers accept them raw, but they are not valid in URLs, and encoding them avoids problems with tools that are strict about it.
• Quotes must not clash with the CSS string. If the CSS uses url("…"), switch the SVG's attribute quotes to single quotes, or encode double quotes as %22.
• Newlines should be collapsed. A raw newline is not allowed inside a CSS string. Replace runs of whitespace with a single space.

Here is the failure from the first bullet, the most common data URI bug:

/* Broken: the first # starts a URL fragment, so the image ends at fill=' */
background-image: url("data:image/svg+xml,<svg xmlns='http://www.w3.org/2000/svg'><path fill='#0f766e' d='M0 0h8v8H0z'/></svg>");

A small encoder

This function applies the rules above in the right order:

export function svgToDataUri(svg) {
  const encoded = svg
    .trim()
    .replace(/\s+/g, " ")   // collapse newlines and indentation
    .replace(/"/g, "'")      // so the CSS can use double quotes
    .replace(/%/g, "%25")    // first, so later escapes are not double-encoded
    .replace(/#/g, "%23")
    .replace(/</g, "%3C")
    .replace(/>/g, "%3E");
  return `url("data:image/svg+xml,${encoded}")`;
}

svgToDataUri(`<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 16 16">
  <path fill="#0f766e" d="M8 1 1 15h14z"/>
</svg>`);

// url("data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 16 16'%3E %3Cpath fill='%230f766e' d='M8 1 1 15h14z'/%3E %3C/svg%3E")

The quote swap assumes the SVG has no single quotes in its attribute values or text. If it does, encode double quotes as %22 instead of swapping them. Collapsing whitespace also changes runs of spaces inside <text> elements, which SVG collapses by default anyway. The SVG to Data URI converter encodes in your browser, as UTF-8 or base64. It sanitizes the SVG first, shows both sizes, and can also decode an existing data URI.

URL-encoded or base64?

/* Same image as base64: valid, but about a third larger before compression */
background-image: url("data:image/svg+xml;base64,PHN2ZyB4bWxucz0i...");

Base64 encodes every three bytes as four characters, so it is about 33 percent larger than the input. URL-encoded SVG is usually much closer to the original size, because most characters in SVG markup pass through unchanged. Gzip and Brotli narrow the difference but do not remove it, since base64 hides the repetition in the markup. Base64 has one advantage: it never needs quote or character escaping, which makes it robust in places such as inline style attributes generated by code. For hand-written CSS, prefer the URL-encoded form. It is smaller and you can still read the shapes and colors.

Data URIs cannot inherit currentColor

An image loaded from a data URI is a separate document. It cannot see the page's CSS, and currentColor inside it refers to its own default color, not the color of the element using it. Changing the icon color then means a second data URI with another fill. CSS masks solve this. Use the SVG as the mask shape, and paint the element with background-color: currentColor:

.icon-check {
  display: inline-block;
  width: 1em;
  height: 1em;
  background-color: currentColor;   /* the icon takes the text color */
  -webkit-mask: url("data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 24 24' fill='none' stroke='black' stroke-width='2'%3E%3Cpath d='m5 12 5 5L20 7'/%3E%3C/svg%3E") center / contain no-repeat;
          mask: url("data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 24 24' fill='none' stroke='black' stroke-width='2'%3E%3Cpath d='m5 12 5 5L20 7'/%3E%3C/svg%3E") center / contain no-repeat;
}

.button:hover .icon-check { color: #0f766e; }

Only the alpha of the mask matters, so the SVG can be drawn in black. The icon now follows the text color, including hover states and themes. Unprefixed mask is supported in current browsers. The -webkit-mask line keeps older Safari and Chromium versions working. If you need more than one color, use an inline SVG or a component instead. The SVG to React component guide covers that route.

Content Security Policy

A strict CSP can block data URIs. Images, including CSS backgrounds, fall under img-src, and data: must be listed explicitly. 'self' does not cover it:

Content-Security-Policy: default-src 'self'; img-src 'self' data:

Masks are covered by img-src too. Allowing data: for images is low risk. Browsers do not run scripts in an SVG used as an image, so a data URI image cannot execute code on your page.

When not to use a data URI

• Large images. Everything in the URI is part of the stylesheet, which blocks rendering. A large illustration inlined in CSS delays the first paint of every page, while a separate file could load later and be cached on its own.
• Images used in many rules. Each occurrence repeats the full markup. Define it once on a custom property, such as --icon-check: url("…"), or use one class.
• Images that change often. Any change invalidates the cached stylesheet. A separate file only invalidates itself.
• Content images. CSS backgrounds have no alternative text. If the image carries meaning, use an img tag with an alt, or an inline SVG with a title.

Before encoding, run the file through the SVG optimizer. Editor metadata and long coordinates cost more inside a stylesheet than anywhere else. If a target does not accept SVG at all, such as some email clients or app store assets, convert it with SVG to PNG instead.