Dynamic Icon Tinting with CSS SVG Masks

The primary constraint of CSS background-image is that the icon's color values are baked into the SVG string. When you need an icon to adapt dynamically on :hover, :active, or in dark mode, CSS Masks provide the solution. This guide explains how to fill SVG with CSS and how to change SVG color using mask-image.

1. The Mask Architecture Pattern

A CSS mask uses the SVG shape as a stencil. Setting the element's background-color: currentColor; causes the current text color to fill the stencil shape. This is how you fill an SVG with CSS dynamically — without modifying the SVG source.

.dynamic-icon {
  display: inline-block;
  width: 20px;
  height: 20px;
  background-color: currentColor;
  
  /* Standard and WebKit Mask Declarations */
  -webkit-mask-image: url('data:image/svg+xml,%3Csvg xmlns=\'http://www.w3.org/2000/svg\' viewBox=\'0 0 24 24\' fill=\'none\' stroke=\'%23000\' stroke-width=\'2\'%3E%3Cpath d=\'M5 12h14M12 5l7 7-7 7\'/%3E%3C/svg%3E');
  mask-image: url('data:image/svg+xml,%3Csvg xmlns=\'http://www.w3.org/2000/svg\' viewBox=\'0 0 24 24\' fill=\'none\' stroke=\'%23000\' stroke-width=\'2\'%3E%3Cpath d=\'M5 12h14M12 5l7 7-7 7\'/%3E%3C/svg%3E');
  
  -webkit-mask-size: contain;
  mask-size: contain;
  -webkit-mask-repeat: no-repeat;
  mask-repeat: no-repeat;
  -webkit-mask-position: center;
  mask-position: center;
}

/* Hover State Color Switching */
.btn:hover .dynamic-icon {
  color: var(--text-primary);
}

2. How to Change SVG Color with CSS

The mask approach lets you change an SVG icon's color entirely in CSS without touching the SVG markup. The SVG only provides the shape — the color is determined by the element's color property:

/* Icon renders in red */
.icon-error { color: #ef4444; }

/* Icon renders in green */
.icon-success { color: #10b981; }

/* Icon adapts to dark mode automatically */
[data-theme="dark"] .icon { color: #fafafa; }

3. How to Change SVG Stroke Color with CSS

For stroke-based icons (line-style vectors where outlines define the shape), the mask technique still works. The SVG's stroke attribute inside the embedded data URI determines the stencil shape, but the visible rendered color on screen comes from background-color: currentColor:

• Stroke Icons: In the source SVG, set stroke="#000" (any solid color) and fill="none". The stroke path becomes the mask stencil. The rendered color is controlled by color in CSS.
• Filled Icons: In the source SVG, set fill="#000". The filled area becomes the mask stencil.

SVG2CSS automatically handles both stroke and fill icons correctly when you select the CSS Mask output tab.

4. Browser Compatibility & Prefixes

Modern Safari, Chromium, and Firefox all support standard mask-image. For full mobile WebKit (iOS) compatibility, vendor prefixing (-webkit-mask-image and -webkit-mask-size) remains recommended. SVG2CSS outputs both standard and prefixed declarations.

5. Masking Solid Shapes vs. Outlined Vectors

• Solid Icons: Use fill="#000000" inside the SVG so the entire silhouette acts as a solid mask.
• Stroke/Line Icons: Use stroke="#000000" fill="none" with a defined stroke-width so the vector lines form the stencil.