Preventing ID Collisions and Broken Gradients in SVGO Optimization

The Problem: Broken Inlined SVGs

When you optimize SVGs using SVGO's default settings and then inline those files into a single HTML page, you often encounter two critical failures: gradients or clip-paths disappear, and elements from different SVGs begin to conflict. This happens because SVGO's preset-default includes plugins like cleanupIds and minifyIds, which rename or remove IDs to save bytes. If an SVG uses a url(#gradient-1) reference and the ID is changed or stripped, the browser cannot resolve the link, leaving the element colorless or invisible.

Furthermore, if two different SVG files both contain an element with id="mask-1", inlining both into one DOM creates a collision. The browser will typically resolve all references to the first instance of that ID it finds, causing the second SVG to render incorrectly.

Prerequisites

• Node.js installed (LTS recommended).
• SVGO v3.0.0 or higher installed via npm: npm install -g svgo.
• A set of SVG files containing internal references (gradients, masks, or filters).

Configuring SVGO for Safe Inlining

To prevent these issues, you must modify the default preset to disable ID cleanup and implement a prefixing strategy. Create a svgo.config.mjs file in your project root.

The Configuration File

export default {
  multipass: true,
  plugins: [
    {
      name: 'preset-default',
      params: {
        overrides: {
          // Prevent SVGO from removing or shortening IDs that might be needed
          cleanupIds: false,
          minifyIds: false,
          // Prevent removal of viewBox to ensure CSS-based scaling works
          removeViewBox: false,
        },
      },
    },
    {
      name: 'prefixIds',
      params: {
        // This ensures IDs are unique per file, preventing collisions when inlined
        prefix: 'svg-unique-id-',
      },
    },
  ],
};

Execution and Permissions

Run the optimizer from your terminal. Ensure you have write permissions for the output directory.

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

# Optimize a directory of files
svgo -f ./assets/svg -o ./assets/dist --config svgo.config.mjs

Key Configuration Decisions

Plugin/Setting	Decision	Impact
cleanupIds: false	Disabled	Prevents removal of IDs that are referenced by url(#id).
prefixIds	Enabled	Adds a unique string to all IDs, preventing DOM collisions in HTML.
removeViewBox: false	Disabled	Preserves the viewBox attribute, allowing the SVG to scale via CSS.
multipass: true	Enabled	Runs optimization repeatedly until no further bytes can be saved.

Verification and Validation

Do not rely solely on file size reduction to verify success. Follow these checks:

1. Plugin Audit: Run svgo --help or check your version to ensure you are on v3+, as v2 uses different plugin naming conventions (e.g., cleanupIDs vs cleanupIds).
2. Visual Diff: Open the original SVG and the optimized SVG side-by-side in a browser. Specifically check for missing gradients or clipped areas.
3. Collision Test: Inline two optimized SVGs into a single .html file. Inspect the DOM to confirm that IDs are prefixed (e.g., svg-unique-id-gradient1) and that both render correctly.

Rollback and Recovery

Because SVGO is a build-time transformation tool, it does not change the state of your source files unless you use the -o (output) flag on the same filename. To roll back changes:

• If you optimized in-place, restore the files from your version control system (e.g., git checkout path/to/svgs/).
• If you used a separate output directory, simply delete the dist folder and re-run the configuration after adjusting the overrides.