Custom dimensions and alignment

Unlike other images, SVG keep proportions when custom width/height ratio does not match icon width/height ratio. That makes it possible to set custom dimensions without worrying about icon being distorted.

By default all icons have height of 1em, width is calculated automatically from original icon's width/height ratio.

To change icon size set font-size.

Example

Stylesheet:

/* Big red alert! */
svg[data-icon="mdi-alert"] {
  font-size: 48px;
  color: #ba3329;
}

/* Different sizes for different paragraphs */
.small {
  font-size: 14px;
  line-height: 20px;
}

.medium {
  font-size: 18px;
  line-height: 26px;
}

HTML:

<div class="alert">
    <iconify-icon data-icon="mdi-alert"></iconify-icon>
</div>
<p class="small">Small text with <span class="iconify" data-icon="noto-alien"></span> alien emoji!</p>
<p class="medium">Someone went overboard with emojis here:
    <span class="iconify" data-icon="emojione-alien-monster"></span>
    <span class="iconify" data-icon="emojione-anguished-face"></span>
    <span class="iconify" data-icon="emojione-astonished-face"></span>
    <span class="iconify" data-icon="emojione-dog-face"></span>
    <span class="iconify" data-icon="emojione-bird"></span>
</p>

Result:

Small text with alien emoji!

Someone went overboard with emojis here:

Usually that's all you need to do. However there are more options.

You can set custom dimensions 3 ways:

  • You can set font-size (as shown above).
  • You can set width and height in stylesheet.
  • You can set data-width and data-height attributes.

    If you set only one of data- attributes, other size is set using width/height ratio of icon. For example, if icon is 768x1024, you set data-height="16", width will be set to 12.

Using data-* attributes

If you set width and height using data-width and/or data-height attributes, Iconify assigns that width/height to SVG icon.

If only one attribute is set, another attribute is calculated using width/height ratio of original icon.

Example:

<iconify-icon data-icon="fa-address-card" data-height="48"></iconify-icon>

Result:

<svg width="64" height="48" viewBox="0 0 2048 1536"><path d="..." fill="currentColor"/></svg>

Original icon's dimensions: 2048x1536

Custom height is 48, so Iconify sets width to 48 * 2048 / 1536 = 64.

It works not only with raw numbers, but with units as well. If instead of 48 value would have been "4.8em", width would have been "6.4em".

Using width and height in css

If you set width or height using stylesheet, Iconify doesn't change any SVG attributes. Height is set to "1em", width is set to "(icon-width / icon-height)em".

Because of that only 1 side is changed, which might result in bad width/height ratio. Therefore you might want to change both width and height or use font-size instead.

Examples are available below.

Examples

Fixed height, dynamic width

This is default mode. By default icons have height of 1em, width is dynamic.

Below is example of changing height to 28px using different methods. There are 2 available methods:

  • Using data-height attribute.
  • Using font-size style.

Stylesheet:

.height-32 {
  height: 32px;
}
.font-32 {
  font-size: 32px;
}

HTML:

<p>Sample wide icon: "fa-battery-3". Default dimensions: 2304x1280.</p>
<p>Sample square icon: "ion-ios-refresh". Default dimensions: 512x512.</p>
<p>Sample thin icon: "whh-business". Default dimensions: 386x1024.</p>
<p>1em height:
    <iconify-icon data-icon="fa-battery-3"></iconify-icon>
    <iconify-icon data-icon="ion-ios-refresh"></iconify-icon>
    <iconify-icon data-icon="whh-business"></iconify-icon>
</p>
<!--
  Correct usage: multiple ways to set height to 32px, width to dynamic value.
-->

<br />
<p>32px height (attribute):
    <iconify-icon data-icon="fa-battery-3" data-height="32"></iconify-icon>
    <iconify-icon data-icon="ion-ios-refresh" data-height="32"></iconify-icon>
    <iconify-icon data-icon="whh-business" data-height="32"></iconify-icon>
</p>
<p>32px height (inline style with font-size):
    <iconify-icon data-icon="fa-battery-3" style="font-size: 32px"></iconify-icon>
    <iconify-icon data-icon="ion-ios-refresh" style="font-size: 32px"></iconify-icon>
    <iconify-icon data-icon="whh-business" style="font-size: 32px"></iconify-icon>
</p>
<p>32px height (css with font-size):
    <iconify-icon class="font-32" data-icon="fa-battery-3"></iconify-icon>
    <iconify-icon class="font-32" data-icon="ion-ios-refresh"></iconify-icon>
    <iconify-icon class="font-32" data-icon="whh-business"></iconify-icon>
</p>
<!--
  Incorrect usage: setting height with inline style or stylesheet, but not setting width.
-->

<br />
<p>Examples of incorrect usage:</p>
<p>32px height (inline style with height):
    <iconify-icon data-icon="fa-battery-3" style="height: 32px"></iconify-icon>
    <iconify-icon data-icon="ion-ios-refresh" style="height: 32px"></iconify-icon>
    <iconify-icon data-icon="whh-business" style="height: 32px"></iconify-icon>
</p>
<p>32px height (css with height):
    <iconify-icon class="height-32" data-icon="fa-battery-3"></iconify-icon>
    <iconify-icon class="height-32" data-icon="ion-ios-refresh"></iconify-icon>
    <iconify-icon class="height-32" data-icon="whh-business"></iconify-icon>
</p>

Result:

Sample wide icon: "fa-battery-3". Default dimensions: 2304x1280.

Sample square icon: "ion-ios-refresh". Default dimensions: 512x512.

Sample thin icon: "whh-business". Default dimensions: 386x1024.

1em height:


32px height (attribute):

32px height (inline style with font-size):

32px height (css with font-size):


Examples of incorrect usage:

32px height (inline style with height):

32px height (css with height):

Icons in example above have shadow to show icon boundaries.

Last 2 examples show incorrect usage. Notice spacing above and below icon that should not be there. If you set height via stylesheet (or inline style), make sure you set width as well. Otherwise you should use font-size.

Never set width: auto in stylesheet, it causes bugs in Internet Explorer that some visitors unfortunately still use.

Fixed width, dynamic height

There are 2 ways to set height, but only 1 way to set width without changing height: using data-width attribute.

Stylesheet:

.width-48 {
  width: 48px;
}

HTML:

<p>Sample wide icon: "fa-battery-3". Default dimensions: 2304x1280.</p>
<p>Sample square icon: "ion-ios-refresh". Default dimensions: 512x512.</p>
<p>Sample thin icon: "whh-business". Default dimensions: 386x1024.</p>
<p>1em height:
    <iconify-icon data-icon="fa-battery-3"></iconify-icon>
    <iconify-icon data-icon="ion-ios-refresh"></iconify-icon>
    <iconify-icon data-icon="whh-business"></iconify-icon>
</p>
<!--
  Correct usage: using data-width to set width to 48px, height to dynamic value.
-->

<br />
<p>48px width (attribute):
    <iconify-icon data-icon="fa-battery-3" data-width="48"></iconify-icon>
    <iconify-icon data-icon="ion-ios-refresh" data-width="48"></iconify-icon>
    <iconify-icon data-icon="whh-business" data-width="48"></iconify-icon>
</p>
<!--
  Incorrect usage: setting width with inline style or stylesheet, but not setting height.
-->

<br />
<p>Examples of incorrect usage:</p>
<p>28px height (inline style):
    <iconify-icon data-icon="fa-battery-3" style="width: 48px"></iconify-icon>
    <iconify-icon data-icon="ion-ios-refresh" style="width: 48px"></iconify-icon>
    <iconify-icon data-icon="whh-business" style="width: 48px"></iconify-icon>
</p>
<p>28px height (css):
    <iconify-icon class="width-48" data-icon="fa-battery-3"></iconify-icon>
    <iconify-icon class="width-48" data-icon="ion-ios-refresh"></iconify-icon>
    <iconify-icon class="width-48" data-icon="whh-business"></iconify-icon>
</p>

Result:

Sample wide icon: "fa-battery-3". Default dimensions: 2304x1280.

Sample square icon: "ion-ios-refresh". Default dimensions: 512x512.

Sample thin icon: "whh-business". Default dimensions: 386x1024.

1em height:


48px width (attribute):


Examples of incorrect usage:

28px height (inline style):

28px height (css):

Icons in example above have shadow to show icon boundaries.

Last 2 examples show incorrect usage. Notice space on left and right of icon. If you set width via stylesheet (or inline style), make sure you set height as well.

Fixed width and height

When you need to fit icon into container, for example make icon square, set both width and height.

There are 2 ways to do it:

  • Using data-width and data-height attributes.
  • Using width and height style.

This example changes icons to 24x24 square.

Stylesheet:

.icon-24 {
  width: 24px;
  height: 24px;
}

HTML:

<p>Sample wide icon: "fa-battery-3". Default dimensions: 2304x1280.</p>
<p>Sample square icon: "ion-ios-refresh". Default dimensions: 512x512.</p>
<p>Sample thin icon: "whh-business". Default dimensions: 386x1024.</p>
<p>1em height:
    <iconify-icon data-icon="fa-battery-3"></iconify-icon>
    <iconify-icon data-icon="ion-ios-refresh"></iconify-icon>
    <iconify-icon data-icon="whh-business"></iconify-icon>
</p>
<br />
<p>24px width and height using data-width and data-height:
    <iconify-icon data-icon="fa-battery-3" data-width="24" data-height="24"></iconify-icon>
    <iconify-icon data-icon="ion-ios-refresh" data-width="24" data-height="24"></iconify-icon>
    <iconify-icon data-icon="whh-business" data-width="24" data-height="24"></iconify-icon>
</p>
<p>24px width and height using inline style:
    <iconify-icon data-icon="fa-battery-3" style="width: 24px; height: 24px"></iconify-icon>
    <iconify-icon data-icon="ion-ios-refresh" style="width: 24px; height: 24px"></iconify-icon>
    <iconify-icon data-icon="whh-business" style="width: 24px; height: 24px"></iconify-icon>
</p>
<p>24px width and height using css:
    <iconify-icon class="icon-24" data-icon="fa-battery-3"></iconify-icon>
    <iconify-icon class="icon-24" data-icon="ion-ios-refresh"></iconify-icon>
    <iconify-icon class="icon-24" data-icon="whh-business"></iconify-icon>
</p>

Result:

Sample wide icon: "fa-battery-3". Default dimensions: 2304x1280.

Sample square icon: "ion-ios-refresh". Default dimensions: 512x512.

Sample thin icon: "whh-business". Default dimensions: 386x1024.

1em height:


24px width and height using data-width and data-height:

24px width and height using inline style:

24px width and height using css:

You can use custom dimensions in background images generated by API as well. Add parameters width and/or height to image URL. Setting one of values to auto in background image URL will result in dimensions matching original icon's dimensions.

Alignment

When width/height ratio does not match original icon's width/height ratio, icon is aligned to center of container (see example above).

However you can change that. You can change horizontal and vertical alignment by adding data-align attribute.

There are 3 options for horizontal alignment:

  • left
  • center (default)
  • right

and 3 options for vertical alignment:

  • top
  • middle (default)
  • bottom

and 2 options for cropping:

  • crop
  • meet (default)

All those options matter only if you set custom width and height that doesn't match icon's width/height ratio.

If you make icon wider than original icon, you can use horizontal alignment to align icon to left, center or right.

If you make icon taller than original icon, you can use vertical alignment to align icon to top, middle or bottom.

You can mix those options by separating them with comma or space: data-align="left,top,meet" data-align="right bottom crop"

Horizontal alignment example

<p>
    Original square icon "noto-soccer-ball":
    <iconify-icon data-icon="noto-soccer-ball"></iconify-icon>
</p>
<!--
  Wide icon
-->

<p>
    Left alignment:
    <iconify-icon data-icon="noto-soccer-ball" data-align="left" style="width: 24px; height: 16px;"></iconify-icon>
</p>
<p>
    Center alignment (default):
    <iconify-icon data-icon="noto-soccer-ball" style="width: 24px; height: 16px;"></iconify-icon>
</p>
<p>
    Right alignment:
    <iconify-icon data-icon="noto-soccer-ball" data-align="right" style="width: 24px; height: 16px;"></iconify-icon>
</p>
<!--
  Tall icon
-->

<p>
    Left alignment with crop:
    <iconify-icon data-icon="noto-soccer-ball" data-align="left crop" style="width: 14px; height: 24px;"></iconify-icon>
</p>
<p>
    Center alignment with crop:
    <iconify-icon data-icon="noto-soccer-ball" data-align="crop" style="width: 14px; height: 24px;"></iconify-icon>
</p>
<p>
    Right alignment with crop:
    <iconify-icon data-icon="noto-soccer-ball" data-align="right top crop" style="width: 14px; height: 24px;"></iconify-icon>
</p>

Result:

Original square icon "noto-soccer-ball":

Left alignment:

Center alignment (default):

Right alignment:

Left alignment with crop:

Center alignment with crop:

Right alignment with crop:

Horizontal alignment without crop makes sense only when icon is too wide, therefore first 3 examples have width bigger than height.

Horizontal alignment with crop makes sense only when icon is too tall, therefore last 2 examples have width smaller than height.

Vertical alignment example

<p>
    Original square icon "noto-soccer-ball":
    <iconify-icon data-icon="noto-soccer-ball"></iconify-icon>
</p>
<!--
  Tall icon
-->

<p>
    Top alignment:
    <iconify-icon data-icon="noto-soccer-ball" data-align="top" style="width: 14px; height: 24px;"></iconify-icon>
</p>
<p>
    Middle alignment (default):
    <iconify-icon data-icon="noto-soccer-ball" style="width: 14px; height: 24px;"></iconify-icon>
</p>
<p>
    Bottom alignment:
    <iconify-icon data-icon="noto-soccer-ball" data-align="bottom" style="width: 14px; height: 24px;"></iconify-icon>
</p>
<!--
  Wide icon
-->

<p>
    Top alignment with crop:
    <iconify-icon data-icon="noto-soccer-ball" data-align="top crop" style="width: 24px; height: 16px;"></iconify-icon>
</p>
<p>
    Middle alignment with crop:
    <iconify-icon data-icon="noto-soccer-ball" data-align="crop" style="width: 24px; height: 16px;"></iconify-icon>
</p>
<p>
    Bottom alignment with crop:
    <iconify-icon data-icon="noto-soccer-ball" data-align="bottom crop" style="width: 24px; height: 16px;"></iconify-icon>
</p>

Result:

Original square icon "noto-soccer-ball":

Top alignment:

Middle alignment (default):

Bottom alignment:

Top alignment with crop:

Middle alignment with crop:

Bottom alignment with crop:

Vertical alignment without crop makes sense only when icon is too tall, therefore first 3 examples have width smaller than height.

Vertical alignment with crop makes sense only when icon is too wide, therefore last 2 examples have width bigger than height.

You can use alignment/crop in background images generated by API as well. Add parameter align to image URL.