Skip to main content
go-swarm-icons
On this page

Providers

Compares constructors, options, and methods for the directory, JSON, Iconify, and chain providers.

The Provider interface and the four concrete implementations: DirectoryProvider, JsonCollectionProvider, IconifyProvider, and ChainProvider.

Overview

The Provider interface defines how icon sources load, check, and list icons. Four implementations are included.

For setup guides and usage examples, see the individual provider pages: Directory Provider, JSON Collection Provider, Iconify Provider, Chain Provider, and Embedded Lucide.

Interface

Go
type Provider interface {
    Get(name string) (*Icon, bool)
    Has(name string) bool
    All() []string
}
Method Description
Get(name) (*Icon, bool) Returns the icon for name. false if not found.
Has(name) bool Reports whether name exists.
All() []string Returns all available icon names.

DirectoryProvider

Loads SVG icons from a directory on disk. Icons are read lazily on first access and cached in memory.

Constructor

Go
func NewDirectoryProvider(dir string, opts ...DirectoryOption) (*DirectoryProvider, error)

Returns ErrProviderError if dir does not exist or is not a directory. Default options: recursive scanning enabled, file extension "svg".

Functional options

Go
type DirectoryOption func(*DirectoryProvider)
Function Signature Default Description
WithRecursive func WithRecursive(recursive bool) DirectoryOption true Enable or disable recursive subdirectory scanning.
WithExtension func WithExtension(ext string) DirectoryOption "svg" File extension to match.

Methods

Method Signature Description
Get (p *DirectoryProvider) Get(name string) (*Icon, bool) Loads from disk on first access, caches the result.
Has (p *DirectoryProvider) Has(name string) bool Checks file existence without loading.
All (p *DirectoryProvider) All() []string Walks the directory and returns all icon names.
Preload (p *DirectoryProvider) Preload() Reads all icons into the cache.

Path traversal protection: names are resolved via filepath.EvalSymlinks and checked against the root directory prefix. Names that escape the root return false.

JsonCollectionProvider

Loads icons from an Iconify JSON collection. The JSON is parsed lazily on first access via sync.Once.

Constructors

Go
func NewJsonCollectionProvider(path string) (*JsonCollectionProvider, error)

Reads the JSON file at path. Returns ErrProviderError on I/O failure.

Go
func NewJsonCollectionFromBytes(data []byte) *JsonCollectionProvider

Creates a provider from raw JSON bytes. Use with go:embed. Does not return an error; parsing is deferred to first access.

Methods

Method Signature Description
Get (p *JsonCollectionProvider) Get(name string) (*Icon, bool) Resolves aliases (max depth 10), applies transforms, caches the result.
Has (p *JsonCollectionProvider) Has(name string) bool Returns true if name is a known icon or alias.
All (p *JsonCollectionProvider) All() []string Returns both icon names and alias names.

IconifyProvider

Fetches icons from the Iconify HTTP API with host fallback. Results are cached in memory.

Constructor

Go
func NewIconifyProvider(prefix string, opts ...IconifyOption) *IconifyProvider

prefix determines the icon set queried (e.g., "mdi", "tabler").

Functional options

Go
type IconifyOption func(*IconifyProvider)
Function Signature Default Description
WithTimeout func WithTimeout(d time.Duration) IconifyOption 10s HTTP request timeout.
WithHosts func WithHosts(hosts []string) IconifyOption 3 Iconify hosts Override the API host list.
WithHTTPClient func WithHTTPClient(client *http.Client) IconifyOption Default with 10s timeout Custom HTTP client.

Default hosts: api.iconify.design, api.simplesvg.com, api.unisvg.com.

Methods

Method Signature Description
Get (p *IconifyProvider) Get(name string) (*Icon, bool) Fetches from the API on cache miss. Tries each host in order.
Has (p *IconifyProvider) Has(name string) bool Triggers an HTTP request if not cached.
All (p *IconifyProvider) All() []string Returns an empty slice (API has no listing endpoint).

ChainProvider

Wraps an ordered list of providers and returns the first match.

Constructor

Go
func NewChainProvider(providers ...Provider) *ChainProvider

Copies the provider slice. Modifying the original after construction has no effect.

Methods

Method Signature Description
Get (c *ChainProvider) Get(name string) (*Icon, bool) Returns the first icon found across the chain.
Has (c *ChainProvider) Has(name string) bool Short-circuits on the first true.
All (c *ChainProvider) All() []string Returns the deduplicated union of all providers' names.

See also

  • Providers: comparison table, "when to use" guidance, and detailed pages for each provider
  • Performance & Caching: caching behavior and throughput guidance per provider
Edit this page

Last updated: