Introduction

go-swarm-icons gives Go projects a single API for loading SVG icons from any source, transforming them with a fluent builder, and rendering accessible <svg> output. Register providers by prefix, resolve icons by name, and get sanitized, ARIA-aware HTML with no JavaScript and no build step.

Three modules

The repository contains three independent Go modules, each with its own go.mod:

• Core module (github.com/frostybee/go-swarm-icons): the icon manager, all four providers, the renderer, and the fluent Icon API. Zero external dependencies beyond the standard library.
• Lucide submodule (github.com/frostybee/go-swarm-icons/lucide): an embedded Lucide icon set (~1,500 icons) bundled via go:embed. Depends on the core module.
• Goldmark submodule (github.com/frostybee/go-swarm-icons/goldmark): a Goldmark extension that adds :icon[prefix:name] inline syntax to Markdown. Depends on the core module and github.com/yuin/goldmark.

Install only the modules the project needs.

The repository also ships a companion CLI, swarm-icons, that downloads any Iconify icon set (Tabler, Heroicons, Material Design, ...) from the npm registry without Node.js. It is the recommended way to add icon sets beyond Lucide. See the CLI Reference.

Minimal example

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

This creates a manager with the embedded Lucide set, resolves the "home" icon, and prints the full <svg> element.

What's next

• Installation: install the core module and optional submodules
• Quick Start: render an icon in eight lines of Go
• Providers: load icons from directories, JSON files, the Iconify API, or combine sources
• CLI Reference: download and manage Iconify icon sets from the terminal
• Guides: icon manipulation, attribute management, aliases, Goldmark integration, sprites, and caching
• API Reference: every exported type, function, and method