# iconly
`iconly` gives you two ways to use SVG icon sprites in the browser: load and cache an external sprite file, or build one from your own icon objects without giving up tree-shaking.
[](https://www.npmjs.com/package/iconly)
[](https://www.npmjs.com/package/iconly)
[Demo](https://codepen.io/ux-ui/pen/zYmyqWR)
---
## Features
- Load and cache external sprite files with `createIconly()`.
- Choose between IndexedDB, memory, and session storage.
- Keep cache entries separate for each sprite file and version.
- Build sprites from icon objects with `iconly/sprite` — no fetch, storage, or extra runtime dependencies.
- Handle failures through the `Result` returned by `init()` and `render()`; neither method throws.
---
## Installation
```bash
npm install iconly
```
---
## Quick Start: external sprite file
```ts
import { createIconly } from 'iconly';
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);
}
```
When `init()` succeeds, iconly adds the SVG sprite to the configured `container`, wrapped in `
...
`.
```html
```
The sprite file should look like this:
```html
```
---
## Quick Start: icon objects
Import icons as ESM modules and let your bundler remove the ones you do not use. iconly only assembles the sprite string and adds it to the DOM.
```ts
import { createSprite } from 'iconly/sprite';
import { search, user, trash } from './icons';
const sprite = createSprite({
icons: [search, user, trash],
container: '#app', // string | HTMLElement, defaults to document.body
});
const result = sprite.render();
if (!result.ok) {
console.error(result.error);
}
```
Icons are plain objects:
```ts
export const search = {
name: 'search', // id for