~2kB gzipped

Demo

Install

$ npm install iconly

Import

import { createIconly } from 'iconly';

Upgrading to v3

• The API is now factory-based: use createIconly() instead of new Iconly().
• init() returns a Result<void> and never throws.
• The injected sprite wrapper is now [data-iconly="iconset"] inside container (instead of #iconset).

See CHANGELOG.md for details.

Usage

const iconLoader = createIconly({
  file: './sprite.svg',
  version: '1.0',
  debug: true,
  storage: 'indexeddb',
});

const result = await iconLoader.init();

if (!result.ok) {
  console.error(result.error);
}

After init(), the SVG sprite is injected into the container inside <div data-iconly="iconset" aria-hidden="true">...</div>.

<svg>
  <use href="#icon-name"></use>
</svg>

File with icons

<svg xmlns="http://www.w3.org/2000/svg" preserveAspectRatio="none" fill="none">
  <symbol id="icon-name" viewBox="0 0 300 300">
    <path ... />
  </symbol>
  ...
</svg>

Options

| Option | Type | Default | Description | |:------------------:|:---------------------------------------:|:---------------:|:----------------------------------------------------------------| | file | string | './icons.svg' | The URL of the SVG file containing the icons. | | version | string | '1.0' | The version of the icon set. | | debug | boolean | false | If true, debug callbacks and logger debug output are enabled. | | container | string \| HTMLElement | document.body | The container element where the icons will be injected. | | storage | 'indexeddb' \| 'memory' \| 'session' | 'indexeddb' | Storage strategy used for caching icon data. | | dbName | string | 'iconlyDB' | IndexedDB database name (only for indexeddb). | | storeName | string | 'icons' | IndexedDB store name (only for indexeddb). | | sessionKeyPrefix | string | 'iconly' | Prefix for SessionStorage keys (only for session). | | logger | { debug?, error? } | undefined | Optional logger implementation for debug/error output. | | onError | (error) => void | undefined | Optional callback invoked on errors. | | onDebug | (...args) => void | undefined | Optional callback invoked for debug messages. |

Error handling

• init() never throws; it returns a Result with ok: false and error details.
• When debug is false, debug messages are suppressed (no onDebug calls and no logger.debug).
• Errors still trigger onError and logger.error (if provided), even when debug is false.
• You can cancel a fetch by calling iconLoader.abort(), which results in a fetch_aborted error code.

License

MIT