Preventing ID Collisions in SVG Icon Sets with SVGO

The Duplicate ID Conflict

When you embed multiple SVG icons into a single HTML page, you often encounter a silent failure: the wrong icon changes color, or a gradient disappears entirely. This happens because many SVG exports use generic IDs like #a, #gradient-1, or #mask-0. Since IDs must be unique across the entire DOM, the browser resolves the reference to the first instance it finds, regardless of which SVG contains it.

The goal is to ensure every ID is unique across your entire project without manually renaming hundreds of elements. SVGO (SVG Optimizer) solves this through the cleanupIDs plugin, which can programmatically rename IDs to avoid collisions while maintaining the internal links between elements.

How cleanupIDs Manages References

The cleanupIDs plugin does more than just delete unused IDs. It scans the SVG for id attributes and their corresponding references (such as url(#id) in a fill or mask). If an ID is referenced, the plugin renames it to a shorter, minified version. If it is not referenced, the plugin removes it entirely to save bytes.

To prevent the collision problem described above, the plugin supports a prefix parameter. By adding a unique string to the start of every ID, you ensure that icon-home#a and icon-user#a remain distinct entities in the browser's DOM.

Implementation Example

To implement a prefixing strategy, you can use the SVGO CLI. This is particularly useful in build pipelines where you can pass a specific prefix based on the filename.

Run the following command in your terminal (requires SVGO installed via npm):

svgo input.svg -o output.svg --config='{"plugins":[{"name":"cleanupIDs","params":{"prefix":"nav-icon-","minify":true}}]}'

Configuration Breakdown

• prefix: Set to nav-icon-. Every ID in the resulting file will start with this string, ensuring it won't clash with other SVGs on the page.
• minify: Set to true. This replaces long, descriptive IDs with short, random characters (e.g., nav-icon-a) to reduce the final file size.

Verification Steps

1. Inspect the Source: Open output.svg in a text editor. Search for id=" and verify that the attributes now begin with your chosen prefix.
2. Check References: Ensure that any fill="url(#...)" or mask="url(#...)" attributes were updated to match the new prefixed IDs.
3. Browser Test: Load the SVG into a browser. If the colors and gradients render correctly, the internal references were preserved.

Trade-offs and Limitations

While cleanupIDs is powerful, it operates primarily on the SVG XML structure. It may not detect references stored in external CSS files or complex JavaScript strings. If your project uses a separate .css file to target specific SVG IDs (e.g., #gradient-1 { stop-color: red; }), the cleanupIDs plugin will rename the ID in the SVG but cannot update your CSS file, breaking the style.

In these cases, you must disable cleanupIDs or use a whitelist to protect specific IDs from being renamed.

Practical Decision Matrix

Scenario	Recommended Setting	Reasoning
Standalone SVG files	minify: true, no prefix	Maximum compression; no collision risk.
Inlined Icon Library	prefix: "[icon-name]-"	Prevents ID collisions across the DOM.
SVGs styled via external CSS	active: false	Prevents breaking CSS selectors.