Working with Icon Sets

The embedded Lucide set covers one icon family. Most projects need icons from other sets (Tabler, Heroicons, Material Design, Font Awesome, and 200+ others). This guide explains where icon sets come from and the different ways to add them, then walks through the most common path end to end.

What are Iconify icon sets

Iconify is an open-source framework that aggregates over 200 icon sets under a unified JSON format. Each set is identified by a prefix (e.g., tabler, heroicons, mdi) and published as an npm package (@iconify-json/tabler, @iconify-json/heroicons, etc.).

go-swarm-icons reads this JSON format natively. The swarm-icons CLI tool downloads sets directly from npm, so no Node.js installation is needed. Once downloaded, the JSON files are consumed by JsonCollectionProvider at runtime.

The swarm-icons CLI

The CLI tool handles icon set management from the terminal: browsing the Iconify catalog, downloading JSON files, checking for updates, searching icons by name, and exporting SVGs. Install it with:

go install github.com/frostybee/go-swarm-icons/cmd/swarm-icons@latest

The CLI is a separate Go module. It is not required by any library import, but it is the primary way to acquire and maintain icon sets during development. The full command reference is in CLI Reference.

Ways to add an icon set

CLI download + JSON file is the recommended starting point. It keeps icons out of the binary, supports version tracking via the swarm-icons.json manifest, and works offline after the initial download.

go:embed is ideal when the project ships as a single binary and disk I/O at runtime is undesirable. Download the JSON file once, embed it with a //go:embed directive, and the file is compiled into the binary.

Iconify HTTP API requires no download step at all. Register a prefix and icons are fetched on demand. The trade-off is a network dependency at runtime, so it suits prototyping or projects that use a handful of icons from many different sets.

Local SVG directory is the right choice for custom icons that are not part of the Iconify ecosystem, or for projects that already have .svg files on disk.

Adding a JSON icon set

This walkthrough covers the most common path: download a set with the CLI, register it as a provider, and use the icons in code.

Browse available sets

Explore the full Iconify catalog from the terminal:

swarm-icons json browse

Filter by name or category:

swarm-icons json browse --search weather

The output shows every set's prefix, name, icon count, category, and license. Sets already downloaded locally are marked with * in the DL column.

Download

Download one or more sets by prefix:

swarm-icons json download tabler heroicons

The JSON files are saved to ./resources/json/ by default, and the swarm-icons.json manifest is created (or updated) to track installed sets and their versions.

Download all 23 popular sets at once:

swarm-icons json download --all

Register the provider

Load the downloaded JSON file and register it under its prefix:

1
import swarmicons "github.com/frostybee/go-swarm-icons"
2
3
manager, err := swarmicons.NewConfig().
4
    AddJsonCollection("tabler", "./resources/json/tabler.json").
5
    AddJsonCollection("heroicons", "./resources/json/heroicons.json").
6
    DefaultPrefix("tabler").
7
    Build()

Use the icons

Resolve icons by prefix:name and render them:

1
import (
2
    "fmt"
3
4
    swarmicons "github.com/frostybee/go-swarm-icons"
5
)
6
7
func main() {
8
    manager, _ := swarmicons.NewConfig().
9
        DiscoverJsonSets("./resources/json/").
10
        DefaultPrefix("tabler").
11
        Build()
12
13
    icon, _ := manager.Get("tabler:home")
14
    fmt.Println(icon.Size(24).Class("icon").ToHTML())
15
16
    // With a default prefix set, bare names resolve to it:
17
    arrow, _ := manager.Get("arrow-right")
18
    fmt.Println(arrow.Size(20).ToHTML())
19
}

Keep sets up to date

Check for newer versions on npm:

swarm-icons json update --dry-run

Apply updates:

swarm-icons json update

The manifest tracks the installed version of each set, so json update only downloads sets with a newer npm release.

Embedding a JSON set in the binary

For single-binary deployments, embed the JSON file at compile time. This eliminates disk I/O at runtime.

Download the JSON file first:

swarm-icons json download tabler

Then embed it:

1
import (
2
    _ "embed"
3
4
    swarmicons "github.com/frostybee/go-swarm-icons"
5
)
6
7
//go:embed resources/json/tabler.json
8
var tablerData []byte
9
10
func main() {
11
    p := swarmicons.NewJsonCollectionFromBytes(tablerData)
12
    manager := swarmicons.Default("tabler", p)
13
14
    icon, _ := manager.Get("home")
15
    fmt.Println(icon.ToHTML())
16
}

NewJsonCollectionFromBytes does not return an error. The JSON is parsed lazily on the first call to Get, Has, or All.

Using the Iconify HTTP API

Register a prefix and icons are fetched from the Iconify API on demand, with no download step needed:

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

This is the fastest way to start using a set, but requires network access at runtime. The provider caches responses in memory, so each icon is fetched only once per process lifetime.

For details on timeout, host fallback, and HTTP client options, see Iconify Provider.

Using local SVG files

For custom icons or sets not available in the Iconify ecosystem, point a directory provider at a folder of .svg files:

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

Each .svg file's name (without extension) becomes the icon name. The directory is scanned lazily on first access and cached in memory.

For details on recursive scanning and subdirectory naming, see Directory Provider.

License and attribution

Icon sets carry their own licenses, independent of this library's MIT license. Downloading a set with the CLI does not change what its license permits or requires.

• Check the license before shipping: swarm-icons json browse shows each set's license in its output, and every downloaded JSON file carries an info.license block with the SPDX identifier and a link.
• Attribution requirements vary: many sets are MIT or ISC (no attribution required in rendered output), but some use CC BY or OFL, which do require credit. A visible credits page or a footer line satisfies most of them.
• Permissive does not mean trademark-free: brand logo sets are the common trap. Simple Icons ships under CC0, yet every glyph in it is a company trademark whose use is governed by that company's brand guidelines, not by the icon set's license.
• Embedded Lucide: the bundled set is ISC licensed; its notice lives in the repository's THIRD-PARTY-NOTICE file along with the licenses of the library's Go dependencies.

See also

• Providers: detailed API and options for each of the four provider types
• JSON Commands: full flag reference for json download, json update, and json browse
• Config Builder: all registration methods for multi-provider setups
• Performance & Caching: choosing the right provider and caching strategy for throughput