Iconify API queries

This tutorial is for developers that want to create their own tools to access Iconify API.

Iconify API has several types of queries:

  • Query to retrieve icon data.
  • Query to render SVG.
  • Administrative queries.
  • Search queries.

Documentation below is not complete. For now, it just lists queries, more details will be added later.

JSONP responses

API supports JSON and JSONP responses.

JSON response returns data in JSON format:

{
   "prefix": "mdi",
   "icons": {
       "account-box": {
           "body": "<path d=\"M6 17c0-2 4-3.1 6-3.1s6 1.1 6 3.1v1H6m9-9a3 3 0 0 1-3 3a3 3 0 0 1-3-3a3 3 0 0 1 3-3a3 3 0 0 1 3 3M3 5v14a2 2 0 0 0 2 2h14a2 2 0 0 0 2-2V5a2 2 0 0 0-2-2H5a2 2 0 0 0-2 2z\" fill=\"currentColor\"/>"
       },
       "account-cash": {
           "body": "<path d=\"M11 8c0 2.21-1.79 4-4 4s-4-1.79-4-4s1.79-4 4-4s4 1.79 4 4m0 6.72V20H0v-2c0-2.21 3.13-4 7-4c1.5 0 2.87.27 4 .72M24 20H13V3h11v17m-8-8.5a2.5 2.5 0 0 1 5 0a2.5 2.5 0 0 1-5 0M22 7a2 2 0 0 1-2-2h-3c0 1.11-.89 2-2 2v9a2 2 0 0 1 2 2h3c0-1.1.9-2 2-2V7z\" fill=\"currentColor\"/>"
       },
       "account": {
           "body": "<path 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\" fill=\"currentColor\"/>"
       },
       "home": {
           "body": "<path d=\"M10 20v-6h4v6h5v-8h3L12 3L2 12h3v8h5z\" fill=\"currentColor\"/>"
       }
   },
   "width": 24,
   "height": 24
}
/mdi.json?icons=account-box,account-cash,account,home&pretty=1

JSONP response is similar to JSON, but it returns a JavaScript file. JSON response is wrapped in a callback. What's the point of JSONP? No need to deal with CORS settings, easy to use, works with very old browsers. Just set up a global callback in visitor's browser, add <script> tag and wait for callback to be called.

Iconify SVG Framework version 1.0 uses JSONP to retrieve icon data. Newer versions use Fetch API, but with JSONP as a backup for browsers that do not support Fetch API.

Example of a JSONP response:

Iconify.addCollection({
   prefix: 'mdi',
   icons: {
       'account-box': {
           body:
               '<path d="M6 17c0-2 4-3.1 6-3.1s6 1.1 6 3.1v1H6m9-9a3 3 0 0 1-3 3a3 3 0 0 1-3-3a3 3 0 0 1 3-3a3 3 0 0 1 3 3M3 5v14a2 2 0 0 0 2 2h14a2 2 0 0 0 2-2V5a2 2 0 0 0-2-2H5a2 2 0 0 0-2 2z" fill="currentColor"/>',
       },
       'account-cash': {
           body:
               '<path d="M11 8c0 2.21-1.79 4-4 4s-4-1.79-4-4s1.79-4 4-4s4 1.79 4 4m0 6.72V20H0v-2c0-2.21 3.13-4 7-4c1.5 0 2.87.27 4 .72M24 20H13V3h11v17m-8-8.5a2.5 2.5 0 0 1 5 0a2.5 2.5 0 0 1-5 0M22 7a2 2 0 0 1-2-2h-3c0 1.11-.89 2-2 2v9a2 2 0 0 1 2 2h3c0-1.1.9-2 2-2V7z" fill="currentColor"/>',
       },
       'account': {
           body:
               '<path 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" fill="currentColor"/>',
       },
       'home': {
           body:
               '<path d="M10 20v-6h4v6h5v-8h3L12 3L2 12h3v8h5z" fill="currentColor"/>',
       },
   },
   width: 24,
   height: 24,
});
/mdi.js?icons=account-box,account-cash,account,home&pretty=1&callback=Iconify.addCollection

By default, API will return JSON data. If you want a JSONP response, do this:

  • Add callback parameter.
  • If query ends with ".json", replace it with ".js" (this is used in queries to retrieve icon data).

Examples:

  • JSON query: /mdi.json?icons=home
  • JSONP query: /mdi.js?icons=home&callback=Iconify.addCollection

Common parameters

All JSON and JSONP queries have several common parameters:

  • callback is used for JSONP queries. It is mandatory for most JSONP queries.
  • pretty is used to format JSON data, making it easy to read. Set to 1 or true to enable.

Query to retrieve icon data

To retrieve icon data, use {prefix}.json?icons={icons}.

Replace "{prefix}" with icon set prefix.

You cannot request data for multiple icon sets in same query. It is one query per icon set.

Number of icons per query is not limited, however be aware that browsers have limit on URL length. Iconify icon components limit URL length to 500. If URL is longer than 500 characters, API query is split into multiple queries.

Parameters:

  • icons is list of icons, without prefix. Separate icon names with comma. It is better to sort icon names alphabetically to make sure they are always requested in the same order. This way there is a chance browser will find matching query in cache and return cached response.

Examples:

  • /mdi.json?icons=account-box,account-cash,account,home
  • /fa-regular.js?icons=circle,check-circle,comments,dot-circle&pretty=1&callback=Iconify.addCollection

API returns IconifyJSON object.

Example:

{
   "prefix": "uil",
   "icons": {
       "lock": {
           "body": "<path d=\"M17 9V7A5 5 0 0 0 7 7v2a3 3 0 0 0-3 3v7a3 3 0 0 0 3 3h10a3 3 0 0 0 3-3v-7a3 3 0 0 0-3-3zM9 7a3 3 0 0 1 6 0v2H9zm9 12a1 1 0 0 1-1 1H7a1 1 0 0 1-1-1v-7a1 1 0 0 1 1-1h10a1 1 0 0 1 1 1z\" fill=\"currentColor\"/>"
       },
       "lock-open-alt": {
           "body": "<path d=\"M12 13a1.49 1.49 0 0 0-1 2.61V17a1 1 0 0 0 2 0v-1.39A1.49 1.49 0 0 0 12 13zm5-4H9V7a3 3 0 0 1 5.12-2.13a3.08 3.08 0 0 1 .78 1.38a1 1 0 1 0 1.94-.5a5.09 5.09 0 0 0-1.31-2.29A5 5 0 0 0 7 7v2a3 3 0 0 0-3 3v7a3 3 0 0 0 3 3h10a3 3 0 0 0 3-3v-7a3 3 0 0 0-3-3zm1 10a1 1 0 0 1-1 1H7a1 1 0 0 1-1-1v-7a1 1 0 0 1 1-1h10a1 1 0 0 1 1 1z\" fill=\"currentColor\"/>"
       }
   },
   "width": 24,
   "height": 24,
   "not_found": ["cake"]
}
/uil.json?icons=cake,lock,lock-open-alt&pretty=1

SVG

Iconify API can also generate SVG, which can be used as a background image.

Query format: /{prefix}/{name}.svg

See using Iconify in CSS for list of parameters.

In addition to parameters described in using Iconify in CSS tutorial, there are few parameters that do not apply to CSS:

  • download forces browser to download file: "download=1".
  • box adds an empty rectangle to SVG that matches viewBox.

Some software ignore viewBox when importing icons. They create groups that automatically resize to fit content. Icons usually have empty pixels around icon, so such software crops those empty pixels when importing SVG. This applies to most UI design tools.

Parameter box adds empty rectangle to SVG, which fixes icon import issue in such software: /mdi/home.svg?box=1.

Combined with download parameter, box parameter this can be used to download SVG that will be imported correctly in software that does not support viewBox: /mdi/home.svg?box=1&download=1.