Iconify API providers

If you are publishing icons, you can host your own Iconify API server that includes only your icons and give access to it to other users. Iconify icon components can retrieve icon data from multiple independent Iconify API servers.

How is it done?

Public API

@my-icons

@icons8

mdi-light:home

@my-icons:line-24:home

@icons8:ios:home

Provider in icon name

Icon names in Iconify icon components have 3 parts:

@api-provider	:	icon-prefix	:	icon-name
provider		prefix		name

• provider points to API source. Starts with "@", can be empty (empty value is used for public Iconify API).
• prefix is name of icon set.
• name is name of icon.

All parts are separated by ":", provider is optional and can be skipped if empty.

Examples:

• @my-icons:line-24:home: icon is retrieved from provider "my-icons". Icon name for that provider is line-24:home.
• mdi-light:home: icon does not have provider, so provider is empty. Empty value is used for public Iconify API.

Provider naming rules are the same as for prefix and name, but with exception that it can be empty:

/^[a-z0-9]+(-[a-z0-9]+)*$/

That regular expression means name must start with character or number, followed by mix of characters, numbers and hyphen. Other characters are not allowed.

Adding API provider

All icon components have function addAPIProvider(). For SVG framework it is Iconify.addAPIProvider(), for other components you need to import it from component.

Example for React component:

jsimport { addAPIProvider } from '@iconify/react';

addAPIProvider('local', {
   // Array of host names.
   // Mutliple hosts allow redundancy: if one host is down, component will query another host.
   resources: ['http://localhost:3000'],
});

Function has 2 parameters:

• provider, string. Provider name. You can also overwrite configuration for default provider by using empty string.
• config, APIConfig. API configuration.

For more details see addAPIProvider documentation from SVG framework.

IconifyProviders

Sometimes using function addAPIProvider() is not simple. For example, if you are using SVG framework that is placed at the end of file before </body>.

There is alternative solution: assigning API providers to global variable IconifyProviders before loading SVG framework. When SVG framework loads, it checks if variable exists and automatically imports all providers from it.

Format is simple: it is an object, where key is provider name, value is configuration. Example, which does the same as example above:

html<script>
   IconifyProviders = {
       local: {
           resources: ['http://localhost:3000'],
       },
   };
</script>
<script src="https://code.iconify.design/3/3.1.1/iconify.min.js"></script>

Components also support it, but components are usually bundled, so you should be able to use addAPIProvider() instead of polluting global variables.

Using API provider

After you add configuration for API provider, which is one simple function call, you can use icons from that API provider.

All you have to do is add provider to icon name. Provider in icon name must match first parameter to addAPIProvider():

html<span class="iconify" data-icon="@icons8:ios-glyphs:color-dropper"></span>

jsximport { addAPIProvider, Icon } from '@iconify/react';

addAPIProvider('local', {
   // Array of host names
   resources: ['http://localhost:3000'],
});

// Demo using provider in icon name
export function renderHomeIcon() {
   return <Icon icon="@local:material-icons:home" />;
}

Authentication

Currently Iconify does not offer authentication options.

If you want to use API providers functionality to host premium icon sets or restrict access, you should add your own authentication logic to both API and clients. Doing that might be tricky due to lack of documentation for internal code, if you need any help, open an issue at Iconify GitHub repository.

It is on a roadmap for premium edition of Iconify API software, which should make hosting premium icon sets very easy. However, that functionality is far away due to lack of development resources. You can help by sponsoring Iconify on GitHub (click "Sponsor" button).

API Config

Type APIConfig passed to addAPIProvider(), is an object.

Properties:

• resources, string[]. List of host names, required. Must start with "https://" or "http://", should not contain path.
• path, string. Path to root directory. Default value is "/".
• rotate, number. Timeout before the next host is used, in milliseconds. Default value is 750.
• timeout, number. Timeout before the API query is considered failed, in milliseconds. Default value is 5000.

Examples:

jsimport { addAPIProvider } from '@iconify/svelte';

// Override default API provider with Iconify API hosted at 'https://iconify.my-project.com'
addAPIProvider('', {
   resources: ['https://iconify.my-project.com'],
});

html<script>
   // Define global variable
   IconifyProviders = {
       // Empty prefix: overwrite default API provider configuration
       '': {
           // Use custom API first, use Iconify public API as backup
           resources: [
               'https://iconify.my-project.com',
               'https://api.iconify.design',
           ],
           // Wait for 1 second before switching API hosts
           rotate: 1000,
       },
   };
</script>
<script src="https://code.iconify.design/3/3.1.1/iconify.min.js"></script>

Provider name

Provider name is specific to your code. It is used only to associate icon with API configuration. Actual API server has no effect on what you call provider.

That means you can change it to whatever you want. Make sure you are using the same provider id in all your code.