JSON icon format

Iconify uses JSON to store icons instead of storing SVG icons separately.

Each JSON file can have unlimited number of icons and icon aliases.

Why JSON?

It makes it easy to store icons in bulk.

Simple format for editing in text editor, supported by all code editors.

Supported by most programming languages without third party libraries.

It is easy to plug in pages. By wrapping JSON data in callback it turns into JavaScript file (also known as JSONP).

Iconify JSON file structure

This is the most basic JSON file:

{
  "icons": {
    "custom-prefix:icon-1": {
      "body": "<g stroke-linecap=\"round\" stroke=\"currentColor\" stroke-width=\"16\" fill=\"none\" fill-rule=\"evenodd\"><path d=\"M64 24c22.143 0 40 17.906 40 40s-17.863 40-40 40h-8\" class=\"animation-delay-0 animation-duration-11 animate-stroke stroke-length-153\"/><path d=\"M40 104l16 16\" class=\"animation-delay-9 animation-duration-2 animate-stroke stroke-length-30\"/><path d=\"M40 104l16-16\" class=\"animation-delay-9 animation-duration-2 animate-stroke stroke-length-30\"/></g>",
      "width": 24,
      "height": 24
    },
    "custom-prefix:icon-2": {
      "body": "<g stroke-linecap=\"round\" stroke-width=\"16\" stroke=\"currentColor\" fill=\"none\" fill-rule=\"evenodd\"><path d=\"M64 24c22.143 0 40 17.906 40 40s-17.863 40-40 40-40-17.906-40-40v-8\" class=\"animation-delay-0 animation-duration-12 animate-stroke stroke-length-230\"/><path d=\"M24 40L8 56\" class=\"animation-delay-10 animation-duration-1 animate-stroke stroke-length-30\"/><path d=\"M24 40l16 16\" class=\"animation-delay-10 animation-duration-1 animate-stroke stroke-length-30\"/></g>",
      "width": 24,
      "height": 24
    }
  }
}

In example above file has only 2 icons: "custom-prefix:icon-1" and "custom-prefix:icon-2". Both are 24x24 icons with different content.

"icons" object

"icons" is the only required object, everything else in JSON file is optional.

Each entry represents one icon. Key is icon name, value is icon data.

List of icon data keys:

  • body - SVG content (everything inside svg tag), string.
  • width, height - Icon dimensions, numbers. If not set, icon is assumed to be 16x16.
  • left, top - Left and top offset of viewBox, numbers. If not set, both values are set to 0.
  • rotate - Default rotation. 0 = none, 1 = 90°, 2 = 180°, 3 = 270°. Default value is 0.
  • hFlip, vFlip - Horizontal and vertical flip, boolean. Default value is false.
  • inlineTop, inlineHeight - top and height values when icon is in inline mode. These are usually set for icons imported from glyph fonts. Values default to top and height values.
  • verticalAlign - vertical alignment value when icon is in inline mode. Default value is -0.143 for icons designed for 14px height (such as FontAwesome 4), -0.125 for other icons.

Sample icon data object (content inside icons['icon-name']) with all attributes:

{
  "body": "<path d=\"M1408 768v480q0 26-19 45t-45 19H960V928H704v384H320q-26 0-45-19t-19-45V768q0-1 .5-3t.5-3l575-474 575 474q1 2 1 6zm223-69l-62 74q-8 9-21 11h-3q-13 0-21-7L832 200 140 777q-12 8-24 7-13-2-21-11l-62-74q-8-10-7-23.5T37 654L756 55q32-26 76-26t76 26l244 204V64q0-14 9-23t23-9h192q14 0 23 9t9 23v408l219 182q10 8 11 21.5t-7 23.5z\" fill=\"currentColor\"/>",
  "width": 1664,
  "height": 1312,
  "inlineTop": -224,
  "inlineHeight": 1792,
  "verticalAlign": -0.143,
  "left": 0,
  "top": 0,
  "rotate": 0,
  "vFlip": false,
  "hFlip": false
}

There are 2 more keys that present in most JSON files: "prefix" and "aliases".

This is sample from FontAwesome 4 icons JSON file:

{
  "prefix": "fa",
  "icons": {
    "angle-left": {
      "body": "<path d=\"M595 288q0 13-10 23L192 704l393 393q10 10 10 23t-10 23l-50 50q-10 10-23 10t-23-10L23 727q-10-10-10-23t10-23l466-466q10-10 23-10t23 10l50 50q10 10 10 23z\" fill=\"currentColor\"/>",
      "width": 608,
      "height": 1280,
      "inlineTop": -256,
      "inlineHeight": 1792,
      "verticalAlign": -0.143
    },
    "bars": {
      "body": "<path d=\"M1536 1088v128q0 26-19 45t-45 19H64q-26 0-45-19t-19-45v-128q0-26 19-45t45-19h1408q26 0 45 19t19 45zm0-512v128q0 26-19 45t-45 19H64q-26 0-45-19T0 704V576q0-26 19-45t45-19h1408q26 0 45 19t19 45zm0-512v128q0 26-19 45t-45 19H64q-26 0-45-19T0 192V64q0-26 19-45T64 0h1408q26 0 45 19t19 45z\" fill=\"currentColor\"/>",
      "height": 1280,
      "inlineTop": -256,
      "width": 1536,
      "inlineHeight": 1792,
      "verticalAlign": -0.143
    },
    "bell-o": {
      "body": "<path d=\"M848 1696q0-16-16-16-59 0-101.5-42.5T688 1536q0-16-16-16t-16 16q0 73 51.5 124.5T832 1712q16 0 16-16zm-666-288h1300q-266-300-266-832 0-51-24-105t-69-103-121.5-80.5T832 256t-169.5 31.5T541 368t-69 103-24 105q0 532-266 832zm1482 0q0 52-38 90t-90 38h-448q0 106-75 181t-181 75-181-75-75-181H128q-52 0-90-38t-38-90q50-42 91-88t85-119.5 74.5-158.5 50-206T320 576q0-152 117-282.5T744 135q-8-19-8-39 0-40 28-68t68-28 68 28 28 68q0 20-8 39 190 28 307 158.5T1344 576q0 139 19.5 260t50 206 74.5 158.5 85 119.5 91 88z\" fill=\"currentColor\"/>",
      "width": 1664,
      "height": 1792,
      "inlineTop": 0,
      "inlineHeight": 1792,
      "verticalAlign": -0.143
    },
    "home": {
      "body": "<path d=\"M1408 768v480q0 26-19 45t-45 19H960V928H704v384H320q-26 0-45-19t-19-45V768q0-1 .5-3t.5-3l575-474 575 474q1 2 1 6zm223-69l-62 74q-8 9-21 11h-3q-13 0-21-7L832 200 140 777q-12 8-24 7-13-2-21-11l-62-74q-8-10-7-23.5T37 654L756 55q32-26 76-26t76 26l244 204V64q0-14 9-23t23-9h192q14 0 23 9t9 23v408l219 182q10 8 11 21.5t-7 23.5z\" fill=\"currentColor\"/>",
      "width": 1664,
      "height": 1312,
      "inlineTop": -224,
      "inlineHeight": 1792,
      "verticalAlign": -0.143
    }
  },
  "aliases": {
    "angle-right": {
      "parent": "angle-left",
      "hFlip": true
    }
  }
}

JSON format is a JavaScript object that has 3 main keys:

  • prefix - prefix for all icons in JSON file.
  • icons - object listing all icons.
  • aliases - object listing icon aliases.

"prefix" string

Prefix is optional. If it exists, prefix is added to all icons and aliases.

In example above prefix is "fa", so for icon "angle-left" full name is "fa:angle-left".

"aliases" object

This object is similar to "icons" object with one major difference: it doesn't have all icon data.

Instead each icon has "parent" attribute that points to parent icon. All missing attribute values are taken from parent icon, all attributes that exist in alias are merged with parent icon's attributes.

In example above "angle-right" is alias for "angle-left" with horizontal flip enabled.

Important: alias and parent icon must have same prefix. "fa:angle-right" can have "fa:angle-left" as parent icon, but "custom-icon:chevron-right" cannot have "fa:chevron-left" as parent icon.

That is not all. If many icons have same value for same attribute, such as many icons have "height: 24", that attribute can be moved to root object. It will be used as default value for icons that do not have that attribute.

Example:

{
  "prefix": "custom-prefix",
  "icons": {
    "icon-1": {
      "body": "<g stroke-linecap=\"round\" stroke=\"currentColor\" stroke-width=\"16\" fill=\"none\" fill-rule=\"evenodd\"><path d=\"M64 24c22.143 0 40 17.906 40 40s-17.863 40-40 40h-8\" class=\"animation-delay-0 animation-duration-11 animate-stroke stroke-length-153\"/><path d=\"M40 104l16 16\" class=\"animation-delay-9 animation-duration-2 animate-stroke stroke-length-30\"/><path d=\"M40 104l16-16\" class=\"animation-delay-9 animation-duration-2 animate-stroke stroke-length-30\"/></g>"
    },
    "icon-2": {
      "body": "<g stroke-linecap=\"round\" stroke-width=\"16\" stroke=\"currentColor\" fill=\"none\" fill-rule=\"evenodd\"><path d=\"M64 24c22.143 0 40 17.906 40 40s-17.863 40-40 40-40-17.906-40-40v-8\" class=\"animation-delay-0 animation-duration-12 animate-stroke stroke-length-230\"/><path d=\"M24 40L8 56\" class=\"animation-delay-10 animation-duration-1 animate-stroke stroke-length-30\"/><path d=\"M24 40l16 16\" class=\"animation-delay-10 animation-duration-1 animate-stroke stroke-length-30\"/></g>"
    },
    "icon-3": {
      "body": "<g stroke-linecap=\"round\" stroke-width=\"16\" stroke=\"currentColor\" fill=\"none\" fill-rule=\"evenodd\"><path d=\"M64 24c22.143 0 40 17.906 40 40s-17.863 40-40 40-40-17.906-40-40v-8\" class=\"animation-delay-0 animation-duration-12 animate-stroke stroke-length-230\"/><path d=\"M24 40L8 56\" class=\"animation-delay-10 animation-duration-1 animate-stroke stroke-length-30\"/><path d=\"M24 40l16 16\" class=\"animation-delay-10 animation-duration-1 animate-stroke stroke-length-30\"/></g>",
      "width": 64,
      "height": 64
    }
  },
  "width": 128,
  "height": 128
}

In this example icons "icon-1" and "icon-2" are 128x128, but "icon-3" is 64x64.

So this is Iconify JSON format. It is very simple. This format is used to store icons in Iconify icons repository, it is used to transfer icon information from API to visitor's browser.

Extra data in Iconify JSON files

There are few extra keys you might find in Iconify JSON files.

All of them have no effect on SVG rendering. They are used only for icons search and website.

Each icon might have "hidden" attribute with value set to boolean "true". That means icon is no longer part of repository, but is kept for backwards compatibility. It tells website to not show icon in icons list.

JSON object might have "categories", "subcategories" and "chars" keys that list categories, sub-categories and characters for icons.

Converting icons from/to Iconify JSON

Iconify repository includes @iconify/tools library. What can you do with Iconify Tools?

  • Import icons from:
    • Directory of SVG icons.
    • SVG font. You can convert from TTF to SVG using FontForge.
    • WebIcons SVG file.
    • Iconify JSON file.
  • Export icons to:
    • Directory on file system.
    • Iconify JSON file.
  • Clean up icons.
  • Crop icons by finding its edges. Requires PhantomJS installed.