Web component function: loadIcons

This tutorial is part of Iconify Icon web component tutorial.

The function loadIcons() retrieves icons from Iconify API.

When to use this function:

• To preload multiple icons that you will use later. This will make sure icon data is available when needed and it will load faster.
• If you need to get icon data as soon as it is available. For example, when rendering a custom component. However, if you need to load just one icon, there is also loadIcon() that is easier to use.

This function is the most efficient way to preload icons that you know will be needed at some point. It loads icon data from Iconify API in bulk, reducing the number of queries.

It is safe to call the function multiple times with the same icon name, component will not load icon data from Iconify API twice. If you set a callback parameter, callback will be called correctly even if icon was loaded with different loadIcons() call, making sure callback is reliable.

Usage

The function has the following parameters:

• icons, (string|IconifyIconName)[]. List of icons to load.
• callback, function. Optional callback to call. Callback is called not only when all icons have been retrieved, but also when part of icons have been retrieved.

The function returns function you can use to stop loading icons. It is needed when, for example, you are loading icons in a custom component, but the component's life cycle ended before icons have loaded, so you need to remove callback.

Icons list

List of icons is an array. Each element can be a string, such as mdi:home or a IconifyIconName object.

Callback

Optional callback has the following parameters:

• loaded, IconifyIconName[]. List of icons that have been loaded.
• missing, IconifyIconName[]. List of icons that are not available on API.
• pending, IconifyIconName[]. List of icons that are still loading.
• unsubscribe, function. Function to call to cancel loading. It is the same as result of loadIcons() call.

IconifyIconName type

IconifyIconName is a simple object with the following properties, all properties are mandatory:

• provider, string. API provider. For public Iconify API value is an empty string "".
• prefix, string. Icon set prefix.
• name, string. Icon name.

Examples

Simple callback that loads one icon:

jsimport { loadIcons } from 'iconify-icon';

const iconName = 'mdi:home';
loadIcons([iconName], (loaded, missing, pending, unsubscribe) => {
   if (loaded.length) {
       console.log(
           `Icon ${iconName} have been loaded and is ready to be renderered.`
       );
       return;
   }

   if (missing.length) {
       console.log(`Icon ${iconName} does not exist.`);
       return;
   }

   if (pending.length) {
       // Pending icons list in this example is empty.
       // If you call loadIcons() with multiple icons, pending list might not be empty, but for one icon it is always empty.
       //
       // Callback is called when something changes, with 1 icon there can only be 2 type of changes: icon has loaded or icon is missing.
   }
});

Async version of loadIcons():

jsimport { loadIcons } from 'iconify-icon';

/**
* Function to load icons, returns Promise
*/
function loadTestIcons(icons) {
   return new Promise((fulfill, reject) => {
       loadIcons(icons, (loaded, missing, pending, unsubscribe) => {
           if (pending.length) {
               // Icons are pending, wait for all to load/fail
               //
               // If pending list is not empty, callback will be called
               // again when all icons are either loaded or missing
               return;
           }
           if (missing.length) {
               reject({
                   loaded,
                   missing,
               });
           } else {
               fulfill({
                   loaded,
               });
           }
       });
   });
}

/**
* Usage example in async function
*/
async function test() {
   // Wait for icons to load
   await loadTestIcons(['jam:info', 'cil:locomotive', 'cil:paper-plane']).catch(
       (err) => {
           console.error('Failed to load icons:', err.missing);
       }
   );

   // Do stuff with loaded icons
   console.log('Loaded!');
}
test();

If you want to load only one icon, there is also loadIcon() that is easier to use.