SVG Diagram Optimization for the Web — From Export to Production

Why Diagram SVGs Need Optimization

Diagramming tools prioritize editability over performance. When you export an SVG from Excalidraw, Draw.io, or Mermaid, the file typically contains:

• Editor metadata — Hidden elements, data attributes, and comments that the tool uses internally but browsers ignore.
• Redundant attributes — Default values explicitly set on every element (e.g., fill="none" on elements that inherit it).
• Excessive precision — Coordinates with 10+ decimal places where 2 would be visually identical.
• Embedded fonts — Full font data embedded inline when a subset or system font would suffice.

Size Impact by Tool

Here's how much optimization matters for a typical medium-complexity diagram (~20 nodes, ~25 edges):

SVGO: The Standard Optimizer

SVGO (SVG Optimizer) is the industry-standard tool for optimizing SVG files. It runs a series of plugins that remove unnecessary data without changing how the SVG renders.

# Install
npm install -g svgo

# Optimize a single file
svgo input.svg -o output.svg

# Optimize all SVGs in a directory
svgo -f ./diagrams/ -o ./diagrams-optimized/

# Preview savings without writing
svgo input.svg --dry-run

Recommended SVGO Config for Diagrams

The default SVGO config works for most SVGs, but diagram SVGs benefit from a few tweaks:

// svgo.config.js
module.exports = {
  plugins: [
    'preset-default',
    'removeDimensions',     // Use viewBox only — better responsive scaling
    'removeOffCanvasPaths', // Remove elements outside the viewport
    {
      name: 'removeAttrs',
      params: {
        attrs: ['data-.*'],  // Strip editor metadata
      },
    },
    {
      name: 'preset-default',
      params: {
        overrides: {
          removeViewBox: false,    // Keep viewBox for responsive sizing
          cleanupIds: false,       // Preserve IDs if using CSS targeting
        },
      },
    },
  ],
};

Embedding SVGs in HTML

There are three main ways to embed SVGs, each with trade-offs:

• <img src="diagram.svg"> — Simplest. Cacheable. But no CSS styling or interactivity. Best for static diagrams.
• Inline <svg> — Full CSS and JavaScript access. But no caching and increases HTML payload. Best for interactive or themed diagrams.
• <object> / <iframe> — Cacheable with interactivity. But more complex and has cross-origin limitations. Rarely the best choice for docs.

For documentation sites, <img> is usually the right choice. For dashboards or interactive docs where you need hover effects or click handlers, inline SVG is worth the trade-off.

Accessibility

Diagrams convey information visually, but not everyone consumes content visually. Make your SVG diagrams accessible:

• Add a role="img" attribute to the root <svg> element.
• Include a <title> element as the first child of <svg> with a short description.
• Add a <desc> element with a longer description of what the diagram shows.
• Use aria-label on the <img> tag if embedding externally.

<svg role="img" viewBox="0 0 800 600">
  <title>User authentication flow</title>
  <desc>
    Flowchart showing login, token validation,
    and session creation steps.
  </desc>
  <!-- diagram content -->
</svg>

CI Automation

For teams that store diagram source files in Git, automate SVG optimization in CI:

# GitHub Actions example
- name: Optimize SVGs
  run: |
    npx svgo -f ./docs/diagrams/ \
      -o ./docs/diagrams/ \
      --config svgo.config.js

This ensures every merged diagram is optimized, regardless of which team member exported it.

Converting to SVG

If your source diagrams are in Excalidraw, Draw.io, or Mermaid format, Orriguii Diagram Converter can convert them to SVG in the browser. You can then run the exported SVGs through SVGO for production use.