Add an opt-in cache for the converted elements

[fastfrwrd]

Closes #255. Revisits the second point of #167.

What this does

cacheRequests caches the SVG text, but the conversion of that text is not cached: useInlineSVG runs getNode() (a DOMParser parse) and a DOM → React conversion on every mount, including on a cache hit — the lazy reducer initializer re-parses cached content. The cost therefore scales with the number of mounts rather than with the number of distinct SVGs, which hurts surfaces that mount the same few SVGs constantly by design: virtualized tables, log lines, trees.

This adds a cacheElements prop, off by default, that keeps the converted element in a module-level cache and reuses it.

<SVG cacheElements src="https://cdn.svglogos.dev/logos/react.svg" />

How the key works

Entries are keyed by the content and by everything else that shapes the output, so nothing changes about what gets rendered:

Input	In the key
content	the preProcessor result, so two different pre-processors of the same src stay separate
title	undefined (keep an existing <title>) is kept distinct from null (remove it) and from any string
description	yes
uniquifyIDs	when it is on, the hash and baseURL each go in as their own part, so no value of one can look like the other; instances with random hashes never share an entry and instances sharing a uniqueHash do

The cache is an LRU capped at 100 entries (ELEMENT_CACHE_MAX_SIZE), and clearElementCache() is exported for apps that want to empty it. With the prop unset there are no reads, no writes and no growth.

convertToElement() and its key builder now hold the parse + convert step that useInlineSVG used in two places (the cached-content initializer and getElement), so both paths share the caching and the preProcessor is applied exactly once per conversion.

Tests

test/cacheElements.spec.tsx and test/modules/elementCache.spec.ts: 28 tests covering the default-off behaviour (including that the cache stays empty), one conversion for N mounts, per-instance props still applied to the reused element, warm cacheStore content, failures not being cached, and one test per keying rule — each of those fails with a wrong title/description/fill/id in the DOM, not just a wrong call count.

Mutation-tested with StrykerJS on the new code: 95.5% on elementCache.ts and 87.5% on convertToElement. The four survivors are equivalent mutants (the marker value used for an undefined title, the empty-string fallback for an absent baseURL, a cache read that can never hit when caching is off, and a store.delete(undefined) no-op the types require).

pnpm run validate passes: lint, typecheck, 122 tests with coverage thresholds met, build, size (7.83 kB CJS / 7.27 kB ESM against the 10 kB limit) and attw.

Verified in a real app

Wired into Grafana with the local build (a portal: resolution) and one prop added to its Icon component, then measured in a table panel with 300 rows and filterable columns:

Run	Icon mounts	SVG parses
without cacheElements	86	86 (same on every repeat)
with cacheElements, cold cache	86	8 — one per distinct icon
with cacheElements, warm cache	86	0

The interaction script was identical in each case: 4 nav open/close cycles, 15 sort toggles across 5 columns, 8 column-filter popups, and a full scroll of 300 rows in both directions. Parses were counted by wrapping DOMParser.prototype.parseFromString and icon mounts by a MutationObserver. Icons rendered correctly throughout — per-instance sizes (16/18/24 px) still applied to the reused elements, no empty SVGs, no console errors.

🤖 Generated with Claude Code

[codesandbox]

Review or Edit in CodeSandbox

Open the branch in Web Editor • VS Code • Insiders

Open Preview

[Copilot]

🟡 Changes recommended

Cache-key collisions can cause incorrect SVG markup to be reused.

Get a fresh assessment by requesting another Copilot review.

Pull request overview

Adds an opt-in LRU cache for converted SVG React elements.

Changes:

• Adds cacheElements and clearElementCache().
• Centralizes conversion and cache-key generation.
• Adds integration, LRU, and documentation coverage.

File summaries

File	Summary
test/modules/elementCache.spec.ts	Tests cache operations and LRU eviction.
test/cacheElements.spec.tsx	Tests integration behavior and keying rules.
src/types.ts	Defines the cacheElements prop.
src/modules/utils.ts	Centralizes conversion and cache-key generation. Critical: unescaped `
src/modules/useInlineSVG.ts	Integrates cached conversion into the hook.
src/modules/elementCache.ts	Implements the LRU element cache.
src/index.tsx	Exports cache clearing and filters the internal prop.
src/config.ts	Defines the cache size limit.
README.md	Documents the new cache option.

Review details

• Files reviewed: 9/9 changed files
• Comments generated: 1
• Review effort level: Lite

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[fastfrwrd]

Maybe this number should be configurable, lmk if you want that and we could add configureElementCache or something?