Rendering SVG

Iconify API can dynamically generate SVG, which can be used in HTML or CSS.

Query

API URI that generates SVG is /{prefix}/{name}.svg, where:

  • "{prefix}" is icon set prefix.
  • "{name}" is icon name.

Optional parameters:

  • color, string. Icon color. Replaces currentColor with specific color, resulting in icon with hardcoded palette.
  • width and height, string | number. Icon dimensions. If only one dimension is specified, such as height, other dimension will be automatically set to match it.
  • flip, string. Flip icon.
  • rotate, string | number. Rotate icon by 90, 180 or 170 degrees.
  • download, boolean. Forces browser to download file.
  • box, boolean. Adds an empty rectangle to SVG that matches viewBox.

Examples:

<img src="https://api.iconify.design/fluent-emoji-flat/alarm-clock.svg" />
/* SVG with hardcoded palette as pseudo element's content */
.test:after {
   content: url('https://api.iconify.design/fluent-emoji-flat/alarm-clock.svg?height=16');
}

/* SVG with hardcoded palette as background image */
.test-icon {
   display: inline-block;
   width: 1em;
   height: 1em;
   background-image: url('https://api.iconify.design/fluent-emoji-flat/alarm-clock.svg');
   background-repeat: no-repeat;
   background-size: 100% 100%;
}

/* Monotone SVG as mask, using currentColor for color */
.test-icon {
   display: inline-block;
   width: 1em;
   height: 1em;
   background-color: currentColor;
   -webkit-mask-image: url('https://api.iconify.design/bi/bell-fill.svg');
   mask-image: url('https://api.iconify.design/bi/bell-fill.svg');
   -webkit-mask-repeat: no-repeat;
   mask-repeat: no-repeat;
   -webkit-mask-size: 100% 100%;
   mask-size: 100% 100%;
}

See how to use icons in CSS on various ways to use icons in CSS.

Color

One downside of using SVG as external resource is it cannot inherit color from parent element. Browsers will use black instead of currentColor.

There are 2 solutions to issue:

  • Use monotone image in CSS as mask instead of background.
  • Specify color using color attribute, changing image color from currentColor to hardcoded color.
.test:after {
   content: url('https://api.iconify.design/bi/bell-fill.svg?height=16&color=%23ba3329');
}

This applies only to monotone icons. Icons that have hardcoded palette don't need color attribute.

URI cannot contain "#", so if you are using hexadecimal color, such as "#ba3329" used in example above, make sure to replace "#" with "%23":

https://api.iconify.design/bi/bell-fill.svg?color=%23ba3329

Download

Parameter "download=1" forces browser to download generated SVG.

This can be used by websites that display icons to create links to download icon.

Box

Parameter "box=1" adds an empty rectangle to generated SVG that matches icon's viewBox.

It is needed when importing SVG to various UI design tools that ignore viewBox. Those tools, such as Sketch, create layer groups that automatically resize to fit content. Icons usually have empty pixels around icon, so such software crops those empty pixels and icon's group ends up being smaller than actual icon, making it harder to align it in design.

Combined with download parameter, box parameter this can be used to download SVG that will be imported correctly in software that does not support viewBox: /mdi/home.svg?box=1&download=1.

Dimensions

You can also specify dimensions to SVG URL as parameters. It is pointless if you are using background-size or mask-size to resize background or mask (see examples above), but it is needed for using SVG as pseudo element's content.

To specify custom dimensions add width and/or height parameters:

https://api.iconify.design/fa-solid/home.svg?width=24&height=24

Numbers without units are treated as pixels, so width=24 and width=24px are identical.

If you specify only one size attribute, other attribute is calculated using width/height ratio of icon. For example, if original icon is 512x1024, setting ?height=16 will result in SVG containing width="8".

There is special keyword auto that sets dimensions to original dimensions of icon:

https://api.iconify.design/fa-solid/home.svg?height=auto

No need to set both width and height to "auto", one parameter is enough (see above about width/height ratio).

Transformations

You can transform SVG generated by Iconify API, same as with placeholder elements.

Possible transformations:

  • Rotations: 90°, 180°, 270°
  • Horizontal and vertical flip

Rotating icon

To rotate an icon, add rotate parameter. Value can be in degrees: rotate=90deg or as numbers: rotate=1 (where 1 = 90deg, 2 = 180deg, 3 = 270deg).

All transformations are done using SVG transforms, not CSS.

No rotation:
90° rotation:
180° rotation:
270° rotation:
HTML:
<span class="sample rotation-0">No rotation:</span><br />
<span class="sample rotation-90">90&deg; rotation:</span><br />
<span class="sample rotation-180">180&deg; rotation:</span><br />
<span class="sample rotation-270">270&deg; rotation:</span><br />
Stylesheet:
.sample:after {
   padding-left: 4px;
}
.rotation-0:after {
   content: url('https://api.iconify.design/noto/spiral-calendar.svg?height=32');
}
.rotation-90:after {
   content: url('https://api.iconify.design/noto/spiral-calendar.svg?height=32&rotate=90deg');
}
.rotation-180:after {
   content: url('https://api.iconify.design/noto/spiral-calendar.svg?height=32&rotate=180deg');
}
.rotation-270:after {
   /* 270deg = 3 */
   content: url('https://api.iconify.design/noto/spiral-calendar.svg?height=32&rotate=3');
}

Flipping icon

To flip an icon, add flip parameter. Value is "horizontal" or "vertical". If you want both, use "horizontal,vertical" or rotate icon by 180 degrees.

All transformations are done using SVG transforms, not CSS.

Original icon:
Horizontal flip:
Vertical flip:
Horizontal and vertical flip:
Mixing rotation and flip:
HTML:
<span class="sample original-icon">Original icon:</span><br />
<span class="sample flip-horizontal">Horizontal flip:</span><br />
<span class="sample flip-vertical">Vertical flip:</span><br />
<span class="sample flip-both">Horizontal and vertical flip:</span><br />
<span class="sample flip-and-rotate">Mixing rotation and flip:</span><br />
Stylesheet:
.sample:after {
   padding-left: 4px;
}
.original-icon:after {
   content: url('https://api.iconify.design/noto/spiral-calendar.svg?height=32');
}
.flip-horizontal:after {
   content: url('https://api.iconify.design/noto/spiral-calendar.svg?height=32&flip=horizontal');
}
.flip-vertical:after {
   content: url('https://api.iconify.design/noto/spiral-calendar.svg?height=32&flip=vertical');
}
.flip-both:after {
   content: url('https://api.iconify.design/noto/spiral-calendar.svg?height=32&flip=horizontal,vertical');
}
.flip-and-rotate:after {
   content: url('https://api.iconify.design/noto/spiral-calendar.svg?height=32&rotate=3&flip=horizontal');
}

You can use both rotation and flip on icon. Icon is flipped first, then rotated.