iconly
Version:
Iconly is designed to load and cache SVG icons in the browser, using IndexedDB to store the data. It retrieves the icons from a given SVG file, stores them in IndexedDB, and inserts them into the DOM for easy access and use.
99 lines (79 loc) • 4.17 kB
Markdown
<div align="center">
<br>
<h1>iconly</h1>
<p><sup>A lightweight utility to load and cache SVG icons in the browser, using IndexedDB to store the data. It retrieves icons from a given SVG file, stores them in IndexedDB, and inserts them into the DOM for easy access and use.</sup></p>
[](https://www.npmjs.com/package/iconly)
[](https://github.com/ux-ui-pro/iconly)
[](https://www.npmjs.org/package/iconly)
<sup>~2kB gzipped</sup>
<a href="https://codepen.io/ux-ui/pen/zYmyqWR">Demo</a>
</div>
<br>
# Install
```console
$ npm install iconly
```
<br>
# Import
```javascript
import { createIconly } from 'iconly';
```
<br>
# 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.
<br>
# Usage
```javascript
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>`.
```HTML
<svg>
<use href="#icon-name"></use>
</svg>
```
<sub>File with icons</sub>
```HTML
<svg xmlns="http://www.w3.org/2000/svg" preserveAspectRatio="none" fill="none">
<symbol id="icon-name" viewBox="0 0 300 300">
<path ... />
</symbol>
...
</svg>
```
<br>
# 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. |
<br>
# 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.
<br>
# License
MIT