Icon data on demand

Main feature of Iconify icon components is ability to load icon data on demand.

Instead of bundling icons, developer passes icon name to icon component, data for used icons is loaded from Iconify API. This approach has the following advantages:

• Only icons displayed on page are loaded.
• Easy to use. No bundling required.
• UI can be made configurable, such as allowing user to choose icons using icon picker.

Process

How does loading icon data on demand work?

<Icon icon="mdi:home" />

<iconify-icon icon="mdi:alert" />

Developer passes icon name as attribute for icon component.

API

Icon Names

Browser

Component requests data for icons from Iconify API.

API

Icon Data

Browser

API sends data for requested icons.

API hosts thousands of icons, but sends only data for icons that were requested.

<svg width="1em" height="1em" viewBox="0 0 24 24" ...>...</svg>

<iconify-icon icon="mdi:alert">#shadow-root<svg width="1em" height="1em" viewBox="0 0 24 24" ...>...</svg></iconify-icon>

Component renders SVG using data retrieved from Iconify API.

Query

To load data for icons, use the following API query: /{prefix}.json?icons={icons}, where:

• "{prefix}" is icon set prefix. To request icons from multiple icon sets, send separate queries for each icon set.
• "{icons}" is list of icon names, separated by comma.

Response is IconifyJSON object.

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

Parameters

Query has one required parameter: icons, described above.

There are also optional parameters:

• pretty, boolean. Formats response, making it easy to read, like shown in example above.

Error response

If icon set is not available, server returns 404 HTTP error.

Missing icons are added to not_found property of response.

Type

For full description of response, see IconifyJSON type documentation.

You can import type from @iconify/types package.

Limitations

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 should be split into multiple queries.

Caching

To help browser cache responses, it is recommended to have the same URLs for queries. To achive that, sort icon names alphabetically, so instead of ?icons=foo,bar or ?icons=bar,foo component always requests ?icons=bar,foo.

Additionally, cache responses in localStorage.

Checking for update

To check if icons were updated since last time, no need to retrieve icons again.

Use /last-modified query. It returns lastModified property of icon set, which you can compare to values in cached responses.