svg

title: Rendering SVG

Rendering SVG

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

Query

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

• [str]{prefix} is icon set prefix.
• [str]{name} is icon name.

Optional parameters:

• [prop]color, [type]string. Icon color. Replaces [prop]currentColor with specific color, resulting in icon with hardcoded palette.
• [prop]width and [prop]height, [type]string | number. Icon dimensions. If only one dimension is specified, such as [prop]height, other dimension will be automatically set to match it.
• [prop]flip, [type]string. Flip icon.
• [prop]rotate, [type]string | number. Rotate icon by 90, 180 or 270 degrees.
• [prop]download, [type]boolean. Forces browser to download file.
• [prop]box, [type]boolean. Adds an empty rectangle to SVG that matches [attr]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 [key]currentColor.

There are 2 solutions to issue:

• Use monotone image in CSS as [prop]mask instead of [prop]background.
• Specify color using [prop]color attribute, changing image color from [prop]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 [attr]color attribute.

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

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

Download

Parameter [str]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 [str]box=1 adds an empty rectangle to generated SVG that matches icon's [attr]viewBox.

It is needed when importing SVG to various UI design tools that ignore [attr]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 [prop]download parameter, [prop]box parameter this can be used to download SVG that will be imported correctly in software that does not support [attr]viewBox: [url]/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 [prop]background-size or [prop]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 [url]width=24 and [url]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 [prop]?height=16 will result in SVG containing [attr]width="8".

There are several special keywords:

• [str]auto sets dimensions to value from [prop]viewBox.
• [str]unset or [str]none remove dimensions.

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

No need to set both width and height to special keyword, 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 {#rotate}

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

All transformations are done using SVG transforms, not CSS.

src: common/css-rotation.html
title: 'HTML:'
css: common/css-rotation.scss
cssTitle: 'Stylesheet:'
demo: true
demoFirst: false
demoTitle: 'Demo:'
class: css-rotation css-demo-common

Flipping icon {#flip}

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

All transformations are done using SVG transforms, not CSS.

src: common/css-flip.html
title: 'HTML:'
css: common/css-flip.scss
cssTitle: 'Stylesheet:'
demo: true
demoFirst: false
demoTitle: 'Demo:'
class: css-flip css-demo-common

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