Showcase

Iconify-style pipelines render icons as CSS masks: a span whose shape is a mask-image, no path in the DOM. The mask adapter morphs that span as it is. svgToIcon reads the markup, maskTarget drives the mask, and your element keeps its classes, its paint and its place in the layout.

WHY THIS PATH

You already ship icons as CSS masks: UnoCSS presetIcons, Tailwind icon plugins, plain Iconify. This animates the elements you have instead of asking you to switch to inline SVG. Any stroke-drawn set Iconify carries qualifies.

HOW IT WORKS

svgToIcon turns markup into morphable data, re-gridding off-grid sets via their viewBox. maskTarget keeps a hidden pair of SVG mask buffers and flips mask-image between them each frame, which is what keeps Safari repainting. Whatever paints the element shows through the moving shape.

THE TRADEOFF

Every frame re-rasterizes the mask on the main thread, so budget it like a hover effect: toggles, nav, empty states. For icon-heavy views, inline SVG stays leaner. Client-only by nature, and fill-drawn sets (Material Symbols) are rejected up front.

One element, no path in the DOM

The shape below is a plain span: its geometry is a referenced SVG mask the driver rewrites per frame, and its color is just CSS showing through.

Shape

Element paint

The morph never touches color. A gradient, an image, plain currentColor: whatever paints the element shows through the moving mask.

Current: menu → x

The whole integration

Two adapter calls around the plain DOM driver. The element is anything with a box: a span from UnoCSS presetIcons, a Tailwind icon plugin, or your own markup.

morphicons/adapters

import { createMorph } from "morphicons/dom";
import { maskTarget, svgToIcon } from "morphicons/adapters";

// what an Iconify pipeline ships: markup, not components
const MENU = svgToIcon(
  '<svg viewBox="0 0 24 24" fill="none" stroke="currentColor"><path d="M4 12h16"/><path d="M4 18h16"/><path d="M4 6h16"/></svg>',
);
const X = svgToIcon(
  '<svg viewBox="0 0 24 24" fill="none" stroke="currentColor"><path d="M18 6 6 18"/><path d="m6 6 12 12"/></svg>',
);

const target = maskTarget(el); // el: your mask-styled <span>
const morph = createMorph(target, MENU);
morph.morphTo(X, "snappy");

// on unmount: morph.destroy(); target.dispose();

Paint versus geometry

Two layers, one contract

The child is laid out, hit-tested, and painted as usual. MorphMask adds its geometry as a compositing mask after the child paints. This is why a gradient belongs in the child, not in the path solver.

A save layer is an offscreen buffer. It costs memory bandwidth per animated frame, so keep masks to small interactive surfaces rather than large icon grids. Web masks re-rasterize every frame too — fine for toggles, not for dense grids.

Flutter API

Pair helpers stay readable

menu.morphTo(x).mask(
  progress: progress,
  child: DecoratedBox(
    decoration: const BoxDecoration(
      gradient: LinearGradient(
        colors: [Color(0xfff29b73), Color(0xff6578d7)],
      ),
    ),
    child: const SizedBox.expand(),
  ),
);

morph_mask.dart

final pair = menu.morphTo(x);

MorphMask.controlled(
  from: pair.from,
  icon: pair.to,
  progress: progress,
  color: Theme.of(context).colorScheme.primary,
  child: DecoratedBox(
    decoration: const BoxDecoration(
      gradient: LinearGradient(
        colors: [Color(0xfff2b78b), Color(0xff7887df)],
      ),
    ),
    child: const SizedBox.expand(),
  ),
);

// The same call is available as pair.mask(...)
// or menu.morphMaskTo(x, progress: progress, child: child).