Iconify Provider

The Iconify provider fetches icons on demand from the HTTP API, giving access to 200,000+ icons across 200+ sets with no files to download.

What it does

IconifyProvider fetches icons from the Iconify HTTP API. It tries multiple hosts in sequence and caches results in memory after the first successful fetch.

When to use it

Reach for this provider during development, prototyping, or in applications where network access is acceptable and the icon set catalog is not known ahead of time.

For offline or build-pipeline use, prefer JSON Collection Provider (the swarm-icons CLI downloads the same sets to disk) or Embedded Lucide. To combine local files with a remote fallback, see Chain Provider.

Setup

Direct construction

1
import swarmicons "github.com/frostybee/go-swarm-icons"
2
3
p := swarmicons.NewIconifyProvider("mdi")
4
manager := swarmicons.Default("mdi", p)
5
6
icon, err := manager.Get("home")

The prefix argument ("mdi") determines which Iconify icon set to query. It maps to the API URL path: https://api.iconify.design/mdi.json?icons=home.

Config builder

1
import swarmicons "github.com/frostybee/go-swarm-icons"
2
3
manager, err := swarmicons.NewConfig().
4
    AddIconifySet("mdi").
5
    DefaultPrefix("mdi").
6
    Build()

Options & behavior

Functional options

1
import (
2
    "time"
3
4
    swarmicons "github.com/frostybee/go-swarm-icons"
5
)
6
7
p := swarmicons.NewIconifyProvider("mdi",
8
    swarmicons.WithTimeout(5 * time.Second),
9
)

Host fallback

The provider tries hosts in order. If the first host returns a non-200 status or a network error, it moves to the next. The default hosts are:

1. https://api.iconify.design
2. https://api.simplesvg.com
3. https://api.unisvg.com

Override the host list with WithHosts:

1
import swarmicons "github.com/frostybee/go-swarm-icons"
2
3
p := swarmicons.NewIconifyProvider("mdi",
4
    swarmicons.WithHosts([]string{"https://my-iconify-mirror.example.com"}),
5
)

Request format

Each Get() call (on a cache miss) sends an HTTP GET request:

1
GET /{prefix}.json?icons={name} HTTP/1.1
2
User-Agent: SwarmIcons/1.0

The response body is limited to 1 MB. Root-level width and height from the response are used as defaults for icons that omit their own dimensions.

All() returns empty

The Iconify API has no endpoint for listing all icons in a set. All() returns an empty slice. Use it only when a listing is not needed, or combine it with a local provider via Chain Provider.

Has() triggers a network request

If the icon is not already cached, Has() calls Get() internally, which makes an HTTP request.

Caching

Results are cached in a thread-safe sync.RWMutex-protected map. The first successful Get() for a name stores the resolved *Icon. Subsequent calls return the cached value with no network I/O. Failed fetches (network errors, non-200 responses, invalid JSON) are not cached; the provider retries on the next call.

Security

Only the configured hosts are contacted. The default host list restricts requests to the three known Iconify API servers. WithHosts() allows overriding this list for self-hosted mirrors or proxies.

Examples

Minimal

1
import (
2
    "fmt"
3
4
    swarmicons "github.com/frostybee/go-swarm-icons"
5
)
6
7
func main() {
8
    p := swarmicons.NewIconifyProvider("mdi")
9
    manager := swarmicons.Default("mdi", p)
10
11
    icon, err := manager.Get("home")
12
    if err != nil {
13
        fmt.Println("fetch failed:", err)
14
        return
15
    }
16
    fmt.Println(icon.Size(24).ToHTML())
17
}

Custom timeout and hosts

1
import (
2
    "fmt"
3
    "time"
4
5
    swarmicons "github.com/frostybee/go-swarm-icons"
6
)
7
8
func main() {
9
    p := swarmicons.NewIconifyProvider("carbon",
10
        swarmicons.WithTimeout(3 * time.Second),
11
        swarmicons.WithHosts([]string{
12
            "https://api.iconify.design",
13
            "https://api.simplesvg.com",
14
        }),
15
    )
16
    manager := swarmicons.Default("carbon", p)
17
18
    icon, err := manager.Get("add")
19
    if err != nil {
20
        fmt.Println("not found:", err)
21
        return
22
    }
23
    fmt.Println(icon.ToHTML())
24
}

JSON Collection vs Iconify API

Choosing a provider

See also

• Providers API reference: full IconifyProvider constructor, methods, and functional options
• Chain Provider: combine Iconify with a local directory for offline fallback
• Performance & Caching: when to use Iconify vs JSON Collection in build pipelines