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.


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.


Icon Names


Component requests data for icons from Iconify API.


Icon Data


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.


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

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

Response is IconifyJSON object.

   "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


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.


For full description of response, see IconifyJSON type documentation.

You can import type from @iconify/types package.


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.


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.