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:
{
"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 list of aliases.
What are aliases? They are variations of other icons. Aliases are used to reduce duplications.
For example, if icons and are identical, only one of those icons can be present in icons property, other icon can be listed in aliases, pointing to original icon:
{
"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 other icon, such as creating a right arrow by using left arrow with horizontal flip:
{
"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.
{
"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
}
}
}
{
"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
}
{
"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
}
}
}
{
"body": "<path d=\"M10 20v-6h4v6h5v-8h3L12 3L2 12h3v8h5z\" fill=\"currentColor\"/>",
"width": 32,
"height": 32,
"left": -4,
"top": -4
}
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:
{
"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:
{
"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:
{
"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
}
{
"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
}
}
}
If dimensions in icon are missing and default values in root object are missing, default value for property (see list of properties above) is used:
{
"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>"
}
}
}
{
"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
}
}
}
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:
{
"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 icons list.
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.