Base64 SVG Not Displaying? A Practical, Engineering-Ready Fix

Base64 SVG Not Displaying? A Practical, Engineering-Ready Fix

This issue shows up in real projects all the time:

• Your img src="data:image/svg+xml;base64,..." looks valid, but nothing renders.
• The same SVG string works in one place and breaks in a CSS background.
• The bug is hard to spot in code review, but expensive to debug.

If this sounds familiar, this guide gives you a repeatable fix path.

Why This Is Hard to Debug

The issue is rarely one broken line. It is usually a chain problem:

1. The SVG source may already be invalid.
2. The encoding may not match the target context.
3. HTML, CSS, and JSON each require different escaping behavior.
4. Security cleanup and rendering rules vary by environment.

That is why one SVG can render in one context and fail in another.

Most Common Root Causes (In Priority Order)

1. Wrong MIME prefix
   Use data:image/svg+xml;base64, or data:image/svg+xml,.

2. Incorrect Base64 encoding flow
   Direct btoa(svg) can break when the SVG contains non-ASCII characters.

3. Escaping mismatches across contexts
   In CSS especially, characters like # and quotes can break loading.

4. Risky or blocked SVG content
   Scripts, event handlers, and external references may be removed or blocked.

5. Broken SVG structure
   Missing viewBox, malformed XML, or invalid tags can prevent rendering.

How We Solve This in SVGView

Instead of asking users to guess, we handle it in three layers.

1) Input Layer: Validate Before Import

In src/lib/svg/import-handler.ts, we:

• enforce file type and size (up to 10MB)
• parse and validate XML with a required <svg> root
• return parse errors for faster diagnosis

This removes invalid input early.

2) Safety Layer: Sanitize Before Preview

In src/lib/svg/sanitizer.ts, we remove:

• <script>
• on* event handler attributes
• <foreignObject>
• external refs (href, xlink:href, src)

This improves security and reduces rendering inconsistency.

3) Output Layer: Provide Both Base64 and URL-Encoded Data URI

In src/lib/svg/exporter.ts:

export function exportToDataUri(svg: string): string {
  const encoded = btoa(unescape(encodeURIComponent(svg)));
  return `data:image/svg+xml;base64,${encoded}`;
}

export function exportToDataUriEncoded(svg: string): string {
  const encoded = encodeURIComponent(svg);
  return `data:image/svg+xml,${encoded}`;
}

So you can:

• choose Base64 for safer compatibility
• choose URL encoding for shorter, readable output
• always get the correct image/svg+xml MIME type

Which Encoding Should You Use?

1. Unknown target environment: choose Base64 first
2. Need shorter and readable strings: choose URL encoding
3. CSS background usage: prefer URL encoding with proper escaping

Use these tools directly:

• SVG to Data URI
• SVG to CSS Background
• SVG Optimizer

A Repeatable Troubleshooting Checklist

1. Confirm prefix: data:image/svg+xml;base64, or data:image/svg+xml,
2. Confirm a valid <svg> root and viewBox
3. Confirm UTF-8-safe encoding flow
4. Confirm escaping for CSS/JSON contexts
5. Sanitize before export
6. Switch Base64 and URL encoding to cross-check quickly

FAQ

Why does it work in <img> but fail in CSS?

Because CSS string parsing has stricter escaping requirements. URL encoding is usually safer there.

Is changing to image/svg+xml always enough?

No. MIME is only one part. Encoding, escaping, and SVG validity still matter.

Is Data URI always better than external SVG files?

No. Data URI is great for small inline assets. Large or heavily reused assets are often better as external files.

Summary

“Base64 SVG not displaying” is not a single bug. It is a pipeline problem.

Once you standardize the flow as validate -> sanitize -> dual encoding -> context match, the issue becomes predictable and manageable.