Rendering modes

This tutorial is part of Iconify Icon web component tutorial.

Web component supports several icon rendering modes.

Modes

There are 4 modes supported by web component:

• "svg": renders <svg> element.
• "style": uses either "bg" or "mask" mode, depending on icon palette.
• "bg": renders <span> element with icon as background image. Usable only for icons that have palette.
• "mask": renders <span> element with icon as mask image. Usable only for icons that do not have palette.

Demo showing 2 icons (one monotone, one with palette) rendered with 4 modes:

svg:

style:

bg:monotone icon shown as black

mask:icon with palette loses color

Code samples

What do these modes actually look like in DOM?

Examples for mdi:home (used in modes demo above) icon:

html<svg
   xmlns="http://www.w3.org/2000/svg"
   width="1em"
   height="1em"
   viewBox="0 0 24 24"
>
   <path fill="currentColor" d="M10 20v-6h4v6h5v-8h3L12 3L2 12h3v8h5Z"></path>
</svg>

svg mode

html<span
   style="
       --svg: url('data:image/svg+xml,%3Csvg xmlns=\'http://www.w3.org/2000/svg\' width=\'24\' height=\'24\' viewBox=\'0 0 24 24\'%3E%3Cpath fill=\'currentColor\' d=\'M10 20v-6h4v6h5v-8h3L12 3L2 12h3v8h5Z\'/%3E%3C/svg%3E');
       width: 1em;
       height: 1em;
       background-color: transparent;
       background-image: var(--svg);
       background-repeat: no-repeat;
       background-size: 100% 100%;
   "
></span>

bg mode

html<span
   style="
       --svg: url('data:image/svg+xml,%3Csvg xmlns=\'http://www.w3.org/2000/svg\' width=\'24\' height=\'24\' viewBox=\'0 0 24 24\'%3E%3Cpath fill=\'currentColor\' d=\'M10 20v-6h4v6h5v-8h3L12 3L2 12h3v8h5Z\'/%3E%3C/svg%3E');
       width: 1em;
       height: 1em;
       background-color: currentcolor;
       -webkit-mask-image: var(--svg);
       -webkit-mask-repeat: no-repeat;
       -webkit-mask-size: 100% 100%;
       mask-image: var(--svg);
       mask-repeat: no-repeat;
       mask-size: 100% 100%;
   "
></span>

mask mode

Why not just render SVG?

You are probably wondering, why is it even needed? Isn't <svg> enough?

Rendering icon as <svg> works for most icons, but it does not always work for icons that use SVG animations.

SVG animations cannot start until document is ready. It might seem like a small thing, but animations not rendering quickly enough can cause bad user experience. This issue can be caused by small things, such as statistics script failing to load or ad code loading slowly. If at least one server that page is loading resources from is unreachable, it might break all animated SVGs on page. Async and defer attributes do not help. Issue can even be caused by script in an iframe.

Animation delay demo

Below is an <iframe> that shows icon rendering issue. It contains animated icon, rendered as <svg> and as background image. Both icons render instantly, but animation in <svg> does not start for few seconds because document is still loading.

Hover demo above to restart it.