Web Integration

Most Go web applications render HTML through html/template, which escapes every string it prints. This guide shows how to pass rendered icons into templates, why marking them as trusted HTML is safe here, and how to expose the manager as a template function.

A minimal handler

Build the manager once at startup and share it across requests; IconManager is safe for concurrent reads and caches resolved icons (see Thread Safety).

1
package main
2
3
import (
4
  "html/template"
5
  "log"
6
  "net/http"
7
8
  swarmicons "github.com/frostybee/go-swarm-icons"
9
  "github.com/frostybee/go-swarm-icons/lucide"
10
)
11
12
var manager = swarmicons.Default("lucide", lucide.Provider())
13
14
var page = template.Must(template.New("page").Parse(`<!DOCTYPE html>
15
<html><body>
16
  <nav>{{ .HomeIcon }} Home</nav>
17
</body></html>`))
18
19
type pageData struct {
20
  HomeIcon template.HTML
21
}
22
23
func handler(w http.ResponseWriter, r *http.Request) {
24
  icon, err := manager.Get("home")
25
  if err != nil {
26
    http.Error(w, "icon lookup failed", http.StatusInternalServerError)
27
    return
28
  }
29
30
  w.Header().Set("Content-Type", "text/html; charset=utf-8")
31
  data := pageData{HomeIcon: template.HTML(icon.ToHTML())}
32
  if err := page.Execute(w, data); err != nil {
33
    log.Printf("render: %v", err)
34
  }
35
}
36
37
func main() {
38
  http.HandleFunc("/", handler)
39
  log.Fatal(http.ListenAndServe(":8080", nil))
40
}

Why `template.HTML(icon.ToHTML())` is safe

html/template escapes plain strings, so passing icon.ToHTML() directly would print the SVG markup as text. Casting to template.HTML tells the template engine the value is trusted markup and must be emitted verbatim.

That trust is earned by the library's pipeline, not assumed: every icon that reaches ToHTML() through the manager has passed the nine-stage sanitization pipeline (scripts, event handlers, and external references stripped), and all attribute values are HTML-escaped during rendering. There is no path from a provider to ToHTML() that skips sanitization.

An `icon` template function

Threading every icon through a data struct gets tedious. A template.FuncMap entry lets templates request icons by name:

1
funcs := template.FuncMap{
2
  "icon": func(name string) (template.HTML, error) {
3
    ic, err := manager.Get(name)
4
    if err != nil {
5
      return "", err
6
    }
7
    return template.HTML(ic.ToHTML()), nil
8
  },
9
}
10
11
page := template.Must(template.New("page").Funcs(funcs).Parse(`
12
<a href="/">{{ icon "lucide:home" }} Home</a>
13
<a href="/search">{{ icon "search" }} Search</a>`))

Because the function returns an error as its second value, a missing icon fails Execute instead of rendering a broken page. For pages that should degrade instead of failing, resolve the error inside the function and return a placeholder, the pattern the demo application uses:

1
func mustIcon(name string) template.HTML {
2
  ic, err := manager.Get(name)
3
  if err != nil {
4
    return template.HTML(`<span class="icon-missing"></span>`)
5
  }
6
  return template.HTML(ic.ToHTML())
7
}

A fallback icon configured on the manager (FallbackIcon with IgnoreNotFound) achieves the same without a custom function; see Aliases & Fallbacks.

Per-request attributes

Get accepts caller attributes, so per-page styling needs no extra machinery:

1
icon, err := manager.Get("home", map[string]string{
2
  "class": "nav-icon",
3
  "style": "color: currentColor",
4
})

Caller attributes sit at the top of the five-layer merge, above global and per-prefix defaults configured once on the manager.

Icon-heavy pages

Inlining the same SVG dozens of times adds up. SpriteCollector deduplicates repeated icons into one hidden <symbol> block referenced by <use> elements; see Sprite Sheets. For provider choice and caching behavior under concurrent load, see Performance & Caching.