feat: add runtime unique SVG ids

[BarrieLAJ]

Summary

• add an opt-in runtimeIds transform and --runtime-ids CLI flag
• generate a stable per-component-instance prefix with useId() while preserving SVGO's file-level prefixIds output
• rewrite matching id, url(#id), href, xlinkHref, and inline style references
• support React classic and automatic runtimes, classic-preact, TypeScript, memo, and forwardRef
• allow custom hook modules with runtimeIds: { importSource: 'custom-runtime/hooks' }

Why

SVGO's prefixIds prevents collisions between different SVG source files, but every rendered instance of the same generated component still contains the same IDs. When an inline SVG component is mounted more than once, fragment references can resolve to definitions in an earlier instance instead of the instance containing the reference.

This option adds uniqueness at render time. It remains disabled by default because applications may rely on predictable generated IDs, as discussed in #322. This also follows the requested direction in #731 without changing existing output unless explicitly enabled.

Behavior

With runtimeIds: true, generated function components call useId(), sanitize its value for use in SVG fragment IDs, and prepend it to the IDs already produced by SVGO. Exact fragment references are rewritten to use the same runtime value.

Plain hash values are only rewritten for href and xlinkHref; this avoids treating colors such as #fff or external URL fragments as ID references. Custom templates that do not emit the generated function component, including class-component templates, retain their static IDs rather than receiving an invalid hook call.

The default hook import is react. The classic-preact runtime uses preact/hooks, and custom runtimes can provide their own import source.

Validation

• pnpm run build
• pnpm test (22 suites, 256 tests, 223 snapshots)
• focused ESLint and Prettier checks for the changed files
• integration coverage proving the transform runs after SVGO prefixing
• regression coverage for TypeScript, automatic JSX, Preact, custom hook imports, memo, forwardRef, colors, external URL fragments, no-ID SVGs, and custom templates

Refs #731
Refs #322

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
svgr	Error		Jul 10, 2026 10:14am

[vercel]

Deployment failed with the following error:

The `vercel.json` schema validation failed with the following message: should NOT have additional property `public`

Learn More: https://vercel.com/docs/concepts/projects/project-configuration