Design system icons often appear dozens of times on one screen, and inline SVG can create a separate subtree per instance. For our monochrome icons, CSS masks removed that markup, simplified updates, and made theming across Shadow DOM easier.

Here's how the approach works, where it scales, and when SVG may still be a better choice.

The problem with inline SVGs

Originally, every one of our icon components resolved to an SVG string. The component parsed the string, cloned an <svg> element, inserted it into its shadow root, and synchronized the node on updates.

That meant every icon on the page carried its own SVG subtree. On icon-heavy screens with lots of menus, tables, toolbars, trees, etc., the same small glyph was parsed, cloned, and stored over and over again.

It also created a fragile update path that produced real bugs, including an update loop and a viewBox regression.

The cost wasn't really about SVG being slow. It was about treating a repeated, static shape as a miniature document per instance.

A mask is the same shape, but cheaper

Our built-in icons are single-color paths using fill="currentColor". For that class of icon, the SVG document isn't the important part. The shape is. The color is just currentColor.

That's exactly what a CSS mask gives you: an image used as an alpha channel, painted with a background color.

So instead of rendering SVG per instance, we publish each icon once as a CSS custom property:

--ch-icon-warning: url("data:image/svg+xml,..."); 

and render the host as the masked shape:

:host([name]) { background-color: currentColor; mask: var(--_icon-src) center / contain no-repeat; -webkit-mask: var(--_icon-src) center / contain no-repeat; } 

--_icon-src points at the requested icon, with the question icon as a CSS fallback:

this.style.setProperty( "--_icon-src", `var(--ch-icon-${name}, var(--ch-icon-question))`, ); 

One adopted stylesheet, one data URI per icon, and no SVG DOM per instance.

That buys us:

  • Less work per named icon. No DOMParser, no cloneNode, no per-instance SVG tree.
  • Cheaper updates. Changing name swaps a custom property instead of rebuilding DOM.
  • Better at scale. A menu or table with dozens of icons creates host elements, not SVG documents.
  • Simpler transforms. rotate and flip apply to the host through CSS variables, so the same transform path works for masked and SVG icons.

Does this scale to 100+ icons?

There are two kinds of scale here: many icon instances, and many unique icons in the set.

100+ instances

This is the sweet spot. Each instance still needs a host element, but it avoids an SVG subtree:

  • one host element
  • no SVG DOM
  • no parse or clone per instance
  • a CSS custom property that selects the icon
  • no SVG subtree rebuild when name changes, though style and paint work still occur

Whether you've got ten icons or a thousand instances drawn from those same ten, the basic DOM structure per instance is the same. Browsers can reuse cached image resources for identical data URIs.

This is exactly where masks shine: menus, tables, trees, toolbars, and buttons repeating the same monochrome glyphs.

100+ unique icons

The rendering path stays cheap. What grows is the registry: CSS payload increases with the number of custom properties for each icon.

Based on our current icon set — 15 icons, about 360 bytes of SVG each — here's a rough payload estimate. The CSS figures include the encoded data URIs and declarations, not the JavaScript icon registry; larger-set figures are extrapolations from the current set:

Current 15 100 icons 1,000 icons
Raw SVG 5.4 KB ~36 KB ~360 KB
Encoded CSS declarations 8.5 KB ~57 KB ~570 KB
Gzipped CSS 1.7 KB ~11 KB ~110 KB

The exact numbers depend on the icon's complexity, but there should be a fairly linear pattern. One hundred icons is comfortably in "ship it" territory: tens of KB of CSS, roughly 10 KB gzipped. A thousand icons is where I'd start splitting sets or generating CSS at build time.

Here's what to watch at that size:

  • :root inheritance. Every icon variable is declared on :root and is available through inheritance. The browser's actual style and memory costs are implementation-dependent. One hundred is usually fine; a thousand is worth profiling for style recalculation and memory.
  • Everything ships. The default icon set is a single record, so 100+ icons means all of them are bundled even if a page only uses five. Splitting by feature or route becomes worthwhile.

Splitting icons into sets

Icon splitting can happen at the CSS level. A charting feature could load a stylesheet with only its chart icon variables, while a WYSIWYG editor loads a separate set.

The component resolves name to a custom property, so it doesn't need to know which stylesheet supplied the icon. Add the matching variable and load its stylesheet; the existing component can render it unchanged.

The short version: masking avoids per-instance SVG DOM, but it doesn't make instance cost independent of page size. A page with hundreds of icons still creates one element per icon and does style and paint work for them, while sharing the same CSS assets.

A set with hundreds of unique icons is also manageable; what grows is the global registry and the fact that all icons ship together, not the per-instance SVG subtree.

The value in custom elements

The core benefit applies anywhere: rendering inline SVG for each icon creates an SVG DOM per instance, whether the app uses React, Vue, Svelte, Angular, or plain HTML. Frameworks can avoid some re-renders, but memoization doesn't remove the per-instance SVG DOM.

An SVG sprite using <symbol> and <use> is another way to reduce duplicated markup, though it still has its own rendering and browser costs.

Shadow DOM can make styling harder

An SVG inside a shadow root isn't reachable by ordinary consumer CSS. You end up exposing ::part(svg), CSS variables, or internal APIs.

A mask on the host is naturally themeable. Custom properties inherit through shadow boundaries, so a theme can override an icon without reaching into component internals:

--ch-icon-warning: url("..."); 

The icon set can be published once, globally

We write the icon set into an adopted stylesheet as :root custom properties. Every shadow root inherits the same variables, so no component needs its own copy of the SVG markup.

The same pattern also makes the component easy to extend. A separately loaded stylesheet can add another icon:

:root { --ch-icon-editor-bold: url("data:image/svg+xml,..."); } 

As long as the variable name matches the component's name sanitization, <ch-icon name="editor-bold"> can use it. Apps can load smaller, feature-specific sets—or add their own icons—without changing the component.

You could do the same in any app, but custom elements make the "one global definition, many shadow roots" pattern especially useful.

It removed imperative DOM synchronization

The old icon component had to synchronize an SVG node into its shadow root on updates. That's where the update loop and viewBox problems came from. Mask mode removes the imperative sync entirely: a name change only updates a CSS variable.

A virtual-DOM framework would handle some of that diffing for you, but the underlying per-instance SVG would still be there.

Icons are nested inside other custom elements

An icon often lives inside a button, menu item, tab, or tree node, each with its own shadow root. Inline SVG gets duplicated at every level. A global CSS variable means you're not embedding the same markup into every component instance.

What we gave up

Masking is best suited to monochrome rendering. A mask can use a multicolor image as a silhouette, but it doesn't preserve the source's colors or gradients. If an icon needs path-level animation or internal structure that consumers must inspect or style, a mask is the wrong tool.

So we didn't remove SVG rendering entirely:

  • URL icons still render real SVG, because external icons can be arbitrary.
  • render="svg" opts a named icon back into SVG DOM for ::part(svg) or direct DOM access.

We also need -webkit-mask for compatibility and a forced-colors fallback so icons stay visible in high-contrast mode.

The takeaway

The best rendering strategy isn't "always SVG" or "always mask." It's matching the representation to the content.

For our named icon set, the icons are monochrome, decorative, and drawn in currentColor. The shape is the data, and CSS is the renderer. Masking opened the door for better performance and extensibility.

Masking was a performance optimization, but the more important win was conceptual: an icon became a styled element instead of a tiny document we had to manage. Custom elements added some additional flexibility, but the model itself works in any framework.