Icon bundles

To improve performance or keep all icons on your servers you can bundle icons with your own scripts. Bundled icons will load instantly instead of retrieving data from API.

To do that simply create bundle (see different methods below) and append it to your script files.

This method only works if you are loading your script synchronously and Iconify is included in footer. If you are loading your script asynchronously or Iconify is placed in header, Iconify might start searching for icons before bundle has loaded, so Iconify would connect to API to retrieve icons, making bundle useless.

You need to place bundle script in footer before </body>:

<!doctype html>
<html lang="en">
<head>
    <!-- header stuff here -->
</head>
<body>

    <!-- page content here -->

    <!-- include Iconify and your bundle before </body> -->
    <script src="https://code.iconify.design/1/1.0.0/iconify.min.js"></script>
    <script src="link_to_your_bundle.js"></script>
</body>
</html>

or you can add Iconify script to bundle too, keeping it all in one file. Then you can place script wherever you want and/or load it asynchronously.

How to find list of used icons?

Before bundling icons you need to know which icons you need to bundle. You can do that by loading pages on your website and using Iconify functions to check what icons are found on page instead of checking each file for icons.

Open your page in browser, open browser's developer tools, switch to console and run this command:

console.log(JSON.stringify(Iconify.listIcons()));

It will output list of icons Iconify has loaded as JavaScript array.

Output will include icons stored in localStorage and sessionStorage because they are added to Iconify list on page load. That means if you are using default settings (sessionStorage is enabled by default), you can browse all pages of your website then run code once - it will list icons used on all pages.

Building your own bundle using Node.js

You can build bundle on your computer using simple Node.js script.

Initialize your Node.js project by running npm init or use existing project. Run this command to install dependencies:

npm install --save-dev @iconify/json-tools @iconify/json

Then create file "bundle.js" with this content:

"use strict";

const fs = require('fs');
const {Collection} = require('@iconify/json-tools');

let icons = [
    // Few Material Design icons
    'mdi-account', 'mdi-home-account',
    // Few FontAwesome 5 icons
    'fa-solid:arrow-alt-circle-down', 'fa-solid:arrow-alt-circle-left', 'fa-solid:arrow-alt-circle-right',
    // Few emojis
    'emojione-cat-face-with-wry-smile', 'emojione:clapping-hands'
];

let output = 'output.js';
let pretty = false;

// Sort icons by collections: filtered[prefix][array of icons]
let filtered = {};
icons.forEach(icon => {
    let parts = icon.split(':'),
        prefix;

    if (parts.length > 1) {
        prefix = parts.shift();
        icon = parts.join(':');
    } else {
        parts = icon.split('-');
        prefix = parts.shift();
        icon = parts.join('-');
    }
    if (filtered[prefix] === void 0) {
        filtered[prefix] = [];
    }
    if (filtered[prefix].indexOf(icon) === -1) {
        filtered[prefix].push(icon);
    }
});

// Parse each collection
let code = '';
Object.keys(filtered).forEach(prefix => {
    let collection = new Collection();
    if (!collection.loadIconifyCollection(prefix)) {
        console.error('Error loading collection', prefix);
        return;
    }

    code += collection.scriptify({
        icons: filtered[prefix],
        optimize: true,
        pretty: pretty
    });
});

// Save code
fs.writeFileSync(output, code, 'utf8');
console.log('Saved bundle to', output, ' (' + code.length + ' bytes)');

Change list of icons in "icons" variable to icons you want to preload, change "output.js" to name of file you want to save bundle to.

Run node bundle to bundle icons.

Then append contents of output.js to your scripts.

Building your own bundle using PHP

You can bundle icons using iconify/json-tools package.

Create Composer project, run this to install dependencies:

composer require iconify/json-tools iconify/json

Then create file "bundle.php" with this code:

<?php

require('./vendor/autoload.php');

$icons = [
    // Few Material Design icons
    'mdi-account', 'mdi-home-account',
    // Few FontAwesome 5 icons
    'fa-solid:arrow-alt-circle-down', 'fa-solid:arrow-alt-circle-left', 'fa-solid:arrow-alt-circle-right',
    // Few emojis
    'emojione-cat-face-with-wry-smile', 'emojione:clapping-hands'
];

$output = 'output.js';
$pretty = false;

// Sort icons by collections: $filtered[prefix][array of icons]
$filtered = [];
foreach ($icons as $icon) {
    $parts = explode(':', $icon);
    if (count($parts) > 1) {
        $prefix = array_shift($parts);
        $icon = implode(':', $parts);
    } else {
        $parts = explode('-', $icon);
        $prefix = array_shift($parts);
        $icon = implode('-', $parts);
    }
    if (!isset($filtered[$prefix])) {
        $filtered[$prefix] = [];
    }
    if (!in_array($icon, $filtered[$prefix])) {
        $filtered[$prefix][] = $icon;
    }
}

// Parse each collection
$code = '';
foreach ($filtered as $prefix => $list) {
    $collection = new \Iconify\JSONTools\Collection();
    if (!$collection->loadIconifyCollection($prefix)) {
        echo "Error loading collection {$prefix}\n";
        continue;
    }

    $code .= $collection->scriptify([
        'icons' => $list,
        'optimize' => true,
        'pretty' => $pretty
    ]);
}

// Save code
file_put_contents($output, $code);
echo 'Saved bundle to ', $output, ' (', strlen($code), " bytes)\n";

Change list of icons and run php bundle.php.

Then append contents of output.js to your scripts.

Disabling API

If you want to keep everything on your servers and you use icons bundle, you might want to disable Iconify API.

To do that change Iconify script tag from iconify.min.js to iconify.basic.min.js

<script src="https://code.iconify.design/1/1.0.0/iconify.basic.min.js"></script>

It is not recommended in case some icons are not included in your bundle, but it is possible. It is one of possible solutions to keeping everything on your own servers (then also make a copy of iconify.basic.js) if your company requires it.

Bundle method is used on this website - icons are bundled with other JavaScript files and served as one JavaScript file.