Icon bundles

JSON

What is an icon bundle?

Icon bundle is a simple JSON object that contains data for multiple icons from the same icon set, wrapped in a callback.

It provides alternative to loading icon data from Iconify API.

Offline use

Icon bundle is the easiest way to make Iconify implementations that rely on API, such as SVG framework and React component, work without the internet access. Instead of loading icon data from API, you can provide icon by loading icon bundle.

Smaller bundle size

For components that do not rely on API, such as basic React component and Vue component, you can use bundles to import multiple icons at the same time instead of importing icons one by one.

Speed up loading

Icon bundles can be used to speed up loading for SVG framework and React component.

Iconify implementation queries API for icon data when it needs to render that icon. Even though loading icon data from API is very fast, it is not instant. By providing icon data for most used icons, you guarantee that icon data is ready when a component needs it, rendering icon instantly.

How to create icons bundle?

You need to:

  1. Generate icon data for bundle. This is done by extracting data for a few icons from a big icon set.
  2. Wrap data in a function that loads icon data or assign it to a variable.

Icon data is a IconifyJSON object, like this:

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

This is the same format that is used to store an icon set, but without metadata and contains only icons that you need.

You need to wrap that data in a function or assign it to a variable. This step is different for different Iconify implementations. For example, in bundles for SVG framework function name is Iconify.addCollection:

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,
});

Each set of data can include only icons from one icon set. If you want to bundle icons from multiple icon sets, you need to repeat same process for each icon set. The only exception is using IconifyPreload for SVG framework, which can be used with an array of data sets (see below).

// Load few icons from Material Design Icons
Iconify.addCollection({
   prefix: 'mdi',
   icons: {
       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,
});

// Load few icons from Unicons
Iconify.addCollection({
   prefix: 'uil',
   icons: {
       home: {
           body:
               '<path d="M21.66 10.25l-9-8a1 1 0 0 0-1.32 0l-9 8a1 1 0 0 0-.27 1.11A1 1 0 0 0 3 12h1v9a1 1 0 0 0 1 1h14a1 1 0 0 0 1-1v-9h1a1 1 0 0 0 .93-.64a1 1 0 0 0-.27-1.11zM13 20h-2v-3a1 1 0 0 1 2 0zm5 0h-3v-3a3 3 0 0 0-6 0v3H6v-8h12zM5.63 10L12 4.34L18.37 10z" fill="currentColor"/>',
       },
       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"/>',
       },
   },
   width: 24,
   height: 24,
});

Generating icon bundle data

There are several ways to generate data for icon bundles:

Wrapping data in callback

You need to make sure icon bundle is loaded before implementation attempts to render an icon. Otherwise, implementation might send a redundant API query to retrieve icon data.

SVG framework

SVG framework supports 2 ways of adding icon bundles:

  • Loading icon bundles before loading Iconify.
  • Loading icon bundles after loading Iconify.

See bundles for SVG framework for details.

Components

Most components expose method addCollection(). You need to use that method to import icon bundles.

See bundles for React component for details.

Examples

Check out code examples for full examples.