IconifyJSON 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 describes IconifyJSON type.

Usage

Icon set in IconifyJSON is created by Iconify Tools or loaded from pre-parsed JSON file.

See Iconify Utils documentation for parsing icon sets and icon sets package documentation.

See Iconify Tools documentation for creating custom icon sets.

Structure

Type IconifyJSON is an object that has the following required properties.

Required properties

• prefix, string. Prefix for icons in JSON file. All icons in an icon set have the same prefix and icon set cannot include icons from other icon sets.
• icons, Record<string,IconifyIcon>. List of icons. Key is icon name, value is IconifyIcon icon data.

Example:

json{
   "prefix": "mdi",
   "icons": {
       "home": {
           "body": "<path d=\"M10 20v-6h4v6h5v-8h3L12 3L2 12h3v8h5z\" fill=\"currentColor\"/>",
           "width": 24,
           "height": 24
       }
   }
}

Other properties are optional: aliases, default values for all icons, metadata.

Icon

Object icons contains data for icons.

Key is icon name. Value is icon data, where body is required and other 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.

In your code you can get default values from defaultIconProps constant from Iconify Utils.

Alias

One optional property of IconifyJSON type is alias, which has type Record<string,IconifyAlias>. Key is alias name, value is IconifyAlias alias data. It represents a list of icon aliases.

What are aliases? They are variations of other icons. Aliases are used to reduce duplications.

For example, if icons home and house are identical, only one of those icons can be present in icons property, another icon can be listed in aliases, pointing to original icon:

json{
   "prefix": "mdi",
   "icons": {
       "house": {
           "body": "<path d=\"M10 20v-6h4v6h5v-8h3L12 3L2 12h3v8h5z\" fill=\"currentColor\"/>",
           "width": 24,
           "height": 24
       }
   },
   "aliases": {
       "home": {
           "parent": "house"
       }
   }
}

Aliases can also include transformations: horizontal and/or vertical flip, 90/180/270 degrees rotation. This allows icon variations by reusing another icon, such as creating a right arrow by using left arrow with horizontal flip:

json{
   "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
       }
   }
}

Alias has the same properties as icons, except for body. It also has additional required property parent that points to parent icon.

Logic for resolving properties of alias:

• For icon dimensions, value set in alias overrides value from parent icon.
• For icon transformations, if value is set in both alias and parent icon, they are merged: horizontal flip + horizontal flip = no horizontal flip, 90 degrees rotation + 180 degrees rotation = 270 degrees rotation.

Source icon set:

json{
   "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
       }
   }
}

Icon set as IconifyJSON

Extracted alias:

json{
   "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
}

Merged "arrow-right" icon as IconifyIcon

Another example:

Source icon set:

json{
   "prefix": "mdi",
   "icons": {
       "house": {
           "body": "<path d=\"M10 20v-6h4v6h5v-8h3L12 3L2 12h3v8h5z\" fill=\"currentColor\"/>",
           "width": 24,
           "height": 24
       }
   },
   "aliases": {
       "house-32": {
           "parent": "house",
           "width": 32,
           "height": 32,
           "left": -4,
           "top": -4
       }
   }
}

Icon set as IconifyJSON

Extracted alias:

json{
   "body": "<path d=\"M10 20v-6h4v6h5v-8h3L12 3L2 12h3v8h5z\" fill=\"currentColor\"/>",
   "width": 32,
   "height": 32,
   "left": -4,
   "top": -4
}

Merged "house-32" icon as IconifyIcon

Default dimensions

If most icons in an icon set have the same dimensions, it does not make sense to list them all for each icon:

json{
   "prefix": "mdi",
   "icons": {
       "home": {
           "body": "<path fill=\"currentColor\" d=\"M10 20v-6h4v6h5v-8h3L12 3L2 12h3v8h5Z\"/>",
           "width": 24,
           "height": 24
       },
       "account": {
           "body": "<path fill=\"currentColor\" d=\"M12 4a4 4 0 0 1 4 4a4 4 0 0 1-4 4a4 4 0 0 1-4-4a4 4 0 0 1 4-4m0 10c4.42 0 8 1.79 8 4v2H4v-2c0-2.21 3.58-4 8-4Z\"/>",
           "width": 24,
           "height": 24
       },
       "arrow-left": {
           "body": "<path fill=\"currentColor\" d=\"M20 11v2H8l5.5 5.5l-1.42 1.42L4.16 12l7.92-7.92L13.5 5.5L8 11h12Z\"/>",
           "width": 24,
           "height": 24
       }
   }
}

To reduce that duplication, root of IconifyJSON object might include default values for icon dimensions:

json{
   "prefix": "mdi",
   "icons": {
       "home": {
           "body": "<path fill=\"currentColor\" d=\"M10 20v-6h4v6h5v-8h3L12 3L2 12h3v8h5Z\"/>"
       },
       "account": {
           "body": "<path fill=\"currentColor\" d=\"M12 4a4 4 0 0 1 4 4a4 4 0 0 1-4 4a4 4 0 0 1-4-4a4 4 0 0 1 4-4m0 10c4.42 0 8 1.79 8 4v2H4v-2c0-2.21 3.58-4 8-4Z\"/>"
       },
       "arrow-left": {
           "body": "<path fill=\"currentColor\" d=\"M20 11v2H8l5.5 5.5l-1.42 1.42L4.16 12l7.92-7.92L13.5 5.5L8 11h12Z\"/>"
       }
   },
   "width": 24,
   "height": 24
}

These default values are used only for icons that do not have dimensions:

With default values:

json{
   "prefix": "mdi",
   "icons": {
       "square": {
           "body": "<path d=\"M3 3v18h18V3\" fill=\"currentColor\"/>"
       },
       "triangle": {
           "body": "<path d=\"M1 21h22L12 2\" fill=\"currentColor\"/>"
       },
       "rectangle": {
           "body": "<path d=\"M4 6v13h16V6H4z\" fill=\"currentColor\"/>"
       },
       "small-circle": {
           "body": "<circle cx=\"8\" cy=\"8\" r=\"8\" fill=\"currentColor\"/>",
           // Custom values override default values
           "width": 16,
           "height": 16
       }
   },
   // Default width and height for icons that do not have width or height
   "width": 24,
   "height": 24
}

Without default values:

json{
   "prefix": "mdi",
   "icons": {
       "square": {
           "body": "<path d=\"M3 3v18h18V3\" fill=\"currentColor\"/>",
           "width": 24,
           "height": 24
       },
       "triangle": {
           "body": "<path d=\"M1 21h22L12 2\" fill=\"currentColor\"/>",
           "width": 24,
           "height": 24
       },
       "rectangle": {
           "body": "<path d=\"M4 6v13h16V6H4z\" fill=\"currentColor\"/>",
           "width": 24,
           "height": 24
       },
       "small-circle": {
           "body": "<circle cx=\"8\" cy=\"8\" r=\"8\" fill=\"currentColor\"/>",
           "width": 16,
           "height": 16
       }
   }
}

Both examples are identical, first example has default values, second example does not.

If dimensions in an icon are missing, and default values in the root object are missing, default value for property (see the list of properties above) is used:

Icon without dimensions, which default to 16:

json{
   "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>"
       }
   }
}

Icon with dimensions:

json{
   "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
       }
   }
}

Both examples are identical, first example has default property values, second example has explicit dimensions.

In all examples above, width and height are used to demonstrate dimensions. But there are also left and top properties and transformations, which are missing in all examples. This is example above with all properties resolved:

json{
   "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,
           "left": 0,
           "top": 0,
           "hFlip": false,
           "vFlip": false,
           "rotate": false
       }
   }
}

Metadata

IconifyJSON can also contain additional data that is used for displaying list of icons.

This is optional data that has no effect on rendering icons, so it was moved to a separate document.

See IconifyJSON metadata for details.

Functions

To parse icon sets, Iconify Utils offers the following functions:

• parseIconSet() parses an entire icon set, calling custom function for every icon.
• getIconData() extracts data for an icon in IconifyIcon format.

To create convert icons to icon sets, use Iconify Tools.