Safely Remove Unused SVG Definitions With Svgo

Dead Definitions Inflate SVG Files

Design tools often export SVG with <defs> blocks that contain gradients, clip paths, or metadata nothing in the graphic actually references. Those unused definitions add bytes without changing what the user sees. Svgo's removeUnused plugin is built to prune them, but it works by scanning for explicit ID references in the markup. Anything it cannot trace gets removed.

How the Plugin Collects and Removes IDs

The plugin runs in two phases. First it walks the SVG document and collects every ID that appears in an attribute such as fill, stroke, href, clip-path, or mask. Second it deletes unreferenced <defs> children, <metadata> blocks, and attributes whose values never match a collected ID. Because the scan is static, it cannot see references assembled by CSS classes or JavaScript at runtime.

Worked Example: Optimizing an Exported Illustration

Suppose a design tool exports illustration.svg with an unused gradient and an XMP metadata block:

<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 100 100">
  <defs>
    <linearGradient id="unused-gradient">...</linearGradient>
    <clipPath id="used-clip">...</clipPath>
    <metadata><rdf:RDF>...</rdf:RDF></metadata>
  </defs>
  <rect clip-path="url(#used-clip)" fill="blue" />
</svg>

Run Svgo from the terminal in the project directory:

svgo illustration.svg -o illustration.optimized.svg --plugins=removeUnused

illustration.svg and illustration.optimized.svg are placeholders; replace them with your actual file names. No special permissions are required beyond read access to the input and write access to the output directory.

Check the size difference with:

du -h illustration.svg illustration.optimized.svg

Expected result: the unused gradient and metadata block disappear, while used-clip remains because the rectangle references it. To see exactly what was removed, run:

svgo illustration.svg --plugins=removeUnused --debug

The debug output lists removed elements. Review it before replacing the original file.

Where Removal Can Break the SVG

removeUnused assumes references are explicit in the SVG markup. If your CSS sets fill: url(#unused-gradient) or a script reads document.getElementById('unused-gradient'), the plugin has no way to know and will strip the gradient. The same applies to <title> or <desc> elements inside <defs> that screen readers may use; removing them reduces accessibility information even though they are not visually referenced.

Limitations and Verification

• Keep a backup of the original SVG. The plugin is destructive and cannot undo itself.
• Open the optimized file in a browser or vector editor and confirm nothing visible is missing.
• Inspect the <defs> section to ensure essential definitions survived.
• If the SVG is later edited in a design tool, the tool may reintroduce unused content, erasing the size gain.

Actionable Closing

Enable removeUnused for straightforward SVGs where all references are explicit. For files that rely on CSS, JavaScript, or accessibility descriptions, audit the debug output or disable the plugin and clean the file manually. The size savings can be substantial, but visual and programmatic verification is the only way to confirm nothing important was lost.