IconifyAlias type

All Iconify libraries share common object structures. They are described as types in @iconify/types NPM package.

For description of types and short explanation of TypeScript see types documentation.

This article explains IconifyAlias type.

IconifyAlias type

Type IconifyAlias represents an alias for icon. It is used in Iconify JSON files.

What is an alias? An alias is icon that reuses another icon's properties.

arrow-left could be an alias of arrow-right with horizontal flip enabled. No need to create new shape when existing shape can be reused with a simple transformation.

battery-empty could be an alias of battery-0 without any changes. This makes it possible to assign multiple names to the same icon.

Structure

Type IconifyAlias is similar to IconifyIcon.

Properties:

  • parent, string. Name of parent icon, required.

Other properties are from IconifyOptional type, they are shared with IconifyIcon type.

IconifyOptional is a simple object with the following properties, all properties are optional:

Properties for viewBox:

  • left, number. Left position of viewBox. Default value is 0.
  • top, number. Top position of viewBox. Default value is 0.
  • width, number. Width of viewBox. Default value is 16.
  • height, number. Height of viewBox. Default value is 16.

Transformations:

  • rotate, number. Number of 90 degrees rotations. Default value is 0.
  • hFlip, boolean. Horizontal flip. Default value is false.
  • vFlip, boolean. Vertical flip. Default value is false.

Parent icon

Parent icon name should not include icon set prefix and parent icon must be present in icon set.

If you use another alias as parent, make sure there are no circular dependencies. For example, if arrow-left is an alias of arrow-right (with horizontal flip), which in turn is an alias of arrow-up (with 90 degrees rotation), which in turn is an alias of arrow-down (with vertical flip), arrow-down could not be an alias of arrow-left because that would create a loop.

To be safe, use only icons as parent, not other aliases.

Merging properties for icon and alias

If, when merging properties, an icon alias has a property that parent icon also has, the following rules apply:

  • hFlip and vFlip. Result is icon.hFlip !== alias.hFlip. That means if both icon and alias are flipped horizontally, result will not be flipped (horizontal flip + horizontal flip cancel each other). If only one of items is flipped horizontally, result will be flipped (horizontal flip + no flip = horizontal flip).
  • rotate. Result is a sum of rotations. That means 90 degrees rotation + 180 degrees rotation = 270 degrees rotation.

For all other properties alias overrides parent icon's value.

Examples of merging icon and alias:

Icon:
{
   "body": "<path d=\"M7 6v12l10-6z\" fill=\"currentColor\"/>",
   "width": 24,
   "height": 24,
   "hFlip": true
}
Alias:
{
   "parent": "icon1",
   "hFlip": true,
   "vFlip": true
}
Merged:
{
   "body": "<path d=\"M7 6v12l10-6z\" fill=\"currentColor\"/>",
   "width": 24,
   "height": 24,
   "parent": "icon1",
   "hFlip": false,
   "vFlip": true
}

In the example above, hFlip + hFlip = false, !vFlip /* default value */ + vFlip = true, other properties were overridden by alias.

Examples

IconifyAlias:
{
   "parent": "arrow-left",
   "hFlip": true
}
IconifyJSON:
{
   "prefix": "bi",
   "icons": {
       "arrow-left": {
           "body": "<g fill=\"currentColor\"><path fill-rule=\"evenodd\" d=\"M5.854 4.646a.5.5 0 0 1 0 .708L3.207 8l2.647 2.646a.5.5 0 0 1-.708.708l-3-3a.5.5 0 0 1 0-.708l3-3a.5.5 0 0 1 .708 0z\"/><path fill-rule=\"evenodd\" d=\"M2.5 8a.5.5 0 0 1 .5-.5h10.5a.5.5 0 0 1 0 1H3a.5.5 0 0 1-.5-.5z\"/></g>",
           "width": 16,
           "height": 16
       }
   },
   "aliases": {
       "arrow-right": {
           "parent": "arrow-left",
           "hFlip": true
       }
   }
}
Merged "arrow-right" icon as IconifyIcon:
{
   "body": "<g fill=\"currentColor\"><path fill-rule=\"evenodd\" d=\"M5.854 4.646a.5.5 0 0 1 0 .708L3.207 8l2.647 2.646a.5.5 0 0 1-.708.708l-3-3a.5.5 0 0 1 0-.708l3-3a.5.5 0 0 1 .708 0z\"/><path fill-rule=\"evenodd\" d=\"M2.5 8a.5.5 0 0 1 .5-.5h10.5a.5.5 0 0 1 0 1H3a.5.5 0 0 1-.5-.5z\"/></g>",
   "width": 16,
   "height": 16,
   "hFlip": true
}
IconifyAlias:
{
   "parent": "house"
}
IconifyJSON:
{
   "prefix": "mdi",
   "icons": {
       "house": {
           "body": "<path d=\"M10 20v-6h4v6h5v-8h3L12 3L2 12h3v8h5z\" fill=\"currentColor\"/>",
           "width": 24,
           "height": 24
       }
   },
   "aliases": {
       "home": {
           "parent": "house"
       }
   }
}
Merged "home" icon as IconifyIcon:
{
   "body": "<path d=\"M10 20v-6h4v6h5v-8h3L12 3L2 12h3v8h5z\" fill=\"currentColor\"/>",
   "width": 24,
   "height": 24
}