JSON Collection Provider

This is the recommended way to use Iconify icon sets in production. Download the sets ahead of time, load them from disk or embed them in the binary, and resolve icons with no HTTP requests at runtime.

What it does

JsonCollectionProvider loads icons from an Iconify JSON collection file. The JSON is parsed once on first access via sync.Once, and resolved icons are cached in memory for all subsequent calls.

When to use it

Reach for this provider when working with Iconify-format JSON icon sets (Tabler, Heroicons, Material Design, and 200+ others), whether loaded from disk at runtime or embedded in the binary via go:embed. It handles alias resolution, per-icon transforms, and root-level dimension defaults automatically.

For .svg files on disk, see Directory Provider. For the pre-bundled Lucide set, see Embedded Lucide.

Setup

From a file on disk

1
import swarmicons "github.com/frostybee/go-swarm-icons"
2
3
p, err := swarmicons.NewJsonCollectionProvider("./tabler.json")
4
if err != nil {
5
    log.Fatal(err)
6
}
7
8
manager := swarmicons.Default("tabler", p)

From embedded bytes

Use go:embed to bundle the JSON file in the binary:

1
import (
2
    _ "embed"
3
4
    swarmicons "github.com/frostybee/go-swarm-icons"
5
)
6
7
//go:embed icons.json
8
var iconsData []byte
9
10
func main() {
11
    p := swarmicons.NewJsonCollectionFromBytes(iconsData)
12
    manager := swarmicons.Default("icons", p)
13
}

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

Config builder

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

Options & behavior

Lazy parsing

The JSON collection is not parsed at construction time. Parsing happens once, on the first call to Get(), Has(), or All(), using sync.Once. All subsequent calls use the parsed data without re-parsing.

If the JSON is malformed or missing the "icons" key, the provider returns false from Get() and Has(), and nil from All().

JSON schema

The provider expects the Iconify JSON format:

1
{
2
  "prefix": "tabler",
3
  "width": 24,
4
  "height": 24,
5
  "icons": {
6
    "home": {
7
      "body": "<path d=\"...\"/>",
8
      "width": 24,
9
      "height": 24
10
    },
11
    "alert": {
12
      "body": "<path d=\"...\"/>"
13
    }
14
  },
15
  "aliases": {
16
    "house": {
17
      "parent": "home"
18
    },
19
    "arrow-right": {
20
      "parent": "arrow-left",
21
      "hFlip": true
22
    }
23
  }
24
}

• icons (required): map of icon name to Iconify icon entries. Each entry has a body (SVG inner content) and optional width, height, left, top, hFlip, vFlip, rotate fields. When the provider builds an Icon from an entry, it applies the rotation (quarter turns, 0-3) and flip transforms, constructs the viewBox attribute, and sanitizes the body; an entry with an empty body yields ErrInvalidSVG.
• aliases (optional): map of alias name to an object with a parent field and optional override fields.
• Root-level width/height: default dimensions inherited by icons that omit their own.

Alias resolution

Aliases reference a parent icon (or another alias) and can override transform fields:

Aliases can chain (alias → alias → icon). Resolution stops at a depth of 10 to prevent infinite loops. A chain deeper than 10 levels returns false from Get().

Icon listing

All() returns the names of all icons and all aliases in the collection. Both are treated as valid icon names.

Caching

Resolved icons are cached in a thread-safe sync.RWMutex-protected map. The first Get() for a name resolves the icon (including alias chains and transforms), caches the result, and returns it. Subsequent calls return the cached *Icon directly.

Examples

Load from file

1
import (
2
    "fmt"
3
    "log"
4
5
    swarmicons "github.com/frostybee/go-swarm-icons"
6
)
7
8
func main() {
9
    p, err := swarmicons.NewJsonCollectionProvider("./tabler.json")
10
    if err != nil {
11
        log.Fatal(err)
12
    }
13
14
    manager := swarmicons.Default("tabler", p)
15
16
    icon, err := manager.Get("home")
17
    if err != nil {
18
        log.Fatal(err)
19
    }
20
    fmt.Println(icon.ToHTML())
21
}

Embed with go:embed

1
import (
2
    _ "embed"
3
    "fmt"
4
5
    swarmicons "github.com/frostybee/go-swarm-icons"
6
)
7
8
//go:embed heroicons.json
9
var heroiconsData []byte
10
11
func main() {
12
    p := swarmicons.NewJsonCollectionFromBytes(heroiconsData)
13
    manager := swarmicons.Default("heroicons", p)
14
15
    icon, err := manager.Get("check-circle")
16
    if err != nil {
17
        fmt.Println("not found")
18
        return
19
    }
20
    fmt.Println(icon.Size(20).ToHTML())
21
}

Discover all JSON sets in a directory

The Config builder can scan a directory for *.json files and register each as a provider using the filename (without extension) as the prefix:

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

Given a ./json/ directory containing tabler.json and mdi.json, this registers two providers under prefixes "tabler" and "mdi".

Choosing a provider

See also

• Providers API reference: full JsonCollectionProvider constructor, methods, and JSON schema details
• Embedded Lucide: a ready-made JSON Collection provider with ~1,500 Lucide icons bundled via go:embed
• Performance & Caching: lazy parsing costs, go:embed patterns, and SSG throughput