Every icon source implements the Provider interface: Get(name), Has(name), and All(). Register a provider under a prefix, and manager.Get("prefix:name") routes to it automatically.
The library ships with four implementations and one ready-made embedded set:
| Provider | Source | Network | Disk | Best for |
|---|---|---|---|---|
| Directory | .svg files in a folder |
No | Yes | Custom or brand icons |
| JSON Collection | Iconify JSON file | No | Yes (or go:embed) |
Production icon sets |
| Iconify API | HTTP API | Yes | No | Prototyping, unknown sets |
| Chain | Multiple providers | Depends | Depends | Local-first with network fallback |
| Embedded Lucide | go:embed in binary |
No | No | Quick start, Lucide-only projects |
The Why go-swarm-icons? page has a decision tree for choosing between them, and the Performance & Caching guide covers throughput trade-offs.
Directory Provider
Load SVG icons from a local folder with lazy caching and path traversal protection.
JSON Collection Provider
Load Iconify JSON icon sets from disk or embed them for production deployments.
Iconify Provider
Access over 200,000 icons across 200+ sets via the Iconify API without local setup.
Chain Provider
Combine multiple providers with priority-based fallback for local overrides plus remote sources.
Embedded Lucide
Get started instantly with the Lucide icon set embedded directly in your Go binary.