Hosting custom icons

This article explains how to host custom Iconify collection on your server.

There are several ways to host custom icons:

  • Bundle custom icons (easy)
  • Hosting PHP version of API (medium)
  • Hosting Node.js version of API (hard)

First solution is easy to setup, but it loads entire set of icons on each page, so list of icons should be rather small.

Last 2 solutions are harder to setup, but they can be used with collections of any size.

You can also use last 2 solutions to host entire Iconify API on your server instead of relying on Iconify API servers.

Bundle custom icons

You can bundle custom icons with your scripts.

This solution is very easy to implement. This solution loads all bundled icons, so it can be used only with small set of icons.

Creating bundle file for custom icons

If you are using custom icons, first you need to convert your custom icons to JSON collection.

Then you need to convert JSON file to JavaScript file. That's very easy:

  • Rename .json file to .js
  • At beginning of file add: Iconify.addCollection(
  • At the end of file add: );

After changes your file will look like this:

  "prefix": "custom-prefix",
  "icons": {
    "icon-1": {
      "body": "<g stroke-linecap=\"round\" stroke=\"currentColor\" stroke-width=\"16\" fill=\"none\" fill-rule=\"evenodd\"><path d=\"M64 24c22.143 0 40 17.906 40 40s-17.863 40-40 40h-8\" class=\"animation-delay-0 animation-duration-11 animate-stroke stroke-length-153\"/><path d=\"M40 104l16 16\" class=\"animation-delay-9 animation-duration-2 animate-stroke stroke-length-30\"/><path d=\"M40 104l16-16\" class=\"animation-delay-9 animation-duration-2 animate-stroke stroke-length-30\"/></g>"
    "icon-2": {
      "body": "<g stroke-linecap=\"round\" stroke-width=\"16\" stroke=\"currentColor\" fill=\"none\" fill-rule=\"evenodd\"><path d=\"M64 24c22.143 0 40 17.906 40 40s-17.863 40-40 40-40-17.906-40-40v-8\" class=\"animation-delay-0 animation-duration-12 animate-stroke stroke-length-230\"/><path d=\"M24 40L8 56\" class=\"animation-delay-10 animation-duration-1 animate-stroke stroke-length-30\"/><path d=\"M24 40l16 16\" class=\"animation-delay-10 animation-duration-1 animate-stroke stroke-length-30\"/></g>"
  "width": 128,
  "height": 128

This sample file has only 2 icons: "custom-prefix:icon-1" and "custom-prefix:icon-2"

Creating bundle file for Iconify icons

Instructions to bundle icons from Iconify collection are in separate tutorial.

Upload generated JavaScript file somewhere on your web server or bundle it with your JavaScript files.

Then simply load it after loading Iconify script:

<script src=""></script>
<script src=""></script>

This code assumes that JavaScript file URL is

Change js file URL to correct file location.

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. If you are bundling Iconify icons set, it would make bundle useless. If you are bundling custom icons, it would result in extra API queries that will return 404 errors.

Therefore you need to load scripts synchronously and place bundle script in footer before </body>:

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

    <!-- page content here -->

    <!-- include Iconify and your bundle before </body> -->
    <script src=""></script>
    <script src="link_to_your_bundle.js"></script>

or you can put Iconify in same bundle so both bundle and Iconify would load as one script.

Method above works well if your custom collection has only few icons.

But what if have large collection or you want to use Iconify load-on-demand technology to serve custom icons or you want to host your own copy of default Iconify icons set? You need to use custom Iconify API.

Custom API

You can host custom Iconify API on your server. Everything you need is available at Iconify GitHub repositories.

Creating custom icons

First you need to create your custom icons and convert them to JSON format.

Instructions for converting icons set to JSON format are in separate tutorial.

Then you need to setup API. There are two ways to do it: PHP and Node.js

To avoid repeating same instructions you need to read following tutorial:

Upload your custom icons to directory "json" on API. Make sure collection prefix matches filename, so if your icons start with "custom-icons:" filename should be "custom-icons.json"

If you do not want to serve default Iconify icon set from your API, set option "serve-default-icons" to false in config.json