Sprite Sheets

When the same icon appears multiple times on a page, each inline <svg> duplicates the full markup. Sprite sheets replace those duplicates with lightweight <use> references to a shared symbol definition, cutting page weight.

How sprites work

Instead of embedding the full SVG markup for each icon, render a lightweight <svg><use href="#i-lucide-home"></use></svg> reference. At the end of the page, inject a hidden sprite sheet containing one <symbol> per unique icon. The browser resolves the <use> references to the symbols in the sheet.

Setup

1
import swarmicons "github.com/frostybee/go-swarm-icons"
2
3
sc := swarmicons.NewSpriteCollector()

NewSpriteCollector returns a ready-to-use collector. It is thread-safe and can be shared across concurrent render passes.

Register symbols

Call Register for each icon that should be available in the sprite sheet:

1
import swarmicons "github.com/frostybee/go-swarm-icons"
2
3
sc := swarmicons.NewSpriteCollector()
4
5
icon, _ := manager.Get("lucide:home")
6
sc.Register("i-lucide-home", icon.Content(), "0 0 24 24")
7
8
icon, _ = manager.Get("lucide:star")
9
sc.Register("i-lucide-star", icon.Content(), "0 0 24 24")

The id parameter should follow the "i-{prefix}-{name}" convention.

Generate the sprite sheet

After rendering page HTML with <use href="#i-..."> references, pass the page content to SpriteSheet:

1
import swarmicons "github.com/frostybee/go-swarm-icons"
2
3
pageHTML := []byte(`<html><body>
4
    <svg><use href="#i-lucide-home"></use></svg>
5
    <svg><use href="#i-lucide-star"></use></svg>
6
    <svg><use href="#i-lucide-home"></use></svg>
7
</body></html>`)
8
9
sheet := sc.SpriteSheet(pageHTML)

SpriteSheet scans the page HTML for <use href="#i-..."> references, matches them against registered symbols, and returns a hidden <svg> element containing one <symbol> per unique referenced icon. Symbols are sorted by ID. Duplicate references produce only one <symbol>.

The returned markup looks like:

1
<svg aria-hidden="true" style="position:absolute;width:0;height:0;overflow:hidden">
2
  <symbol id="i-lucide-home" viewBox="0 0 24 24">...</symbol>
3
  <symbol id="i-lucide-star" viewBox="0 0 24 24">...</symbol>
4
</svg>

SpriteSheet returns nil if no matching references are found in the page HTML.

ID namespacing

When a symbol is registered, internal SVG references (id, url(#...), href="#...") in the body are automatically suffixed to prevent collisions. For an id of "i-lucide-star", the suffix is "lucide-star" (the id with the "i-" prefix stripped).

For example, a body containing id="g" and url(#g) becomes id="g-lucide-star" and url(#g-lucide-star). This prevents two symbols from sharing the same internal reference IDs.

Reuse across pages

Call Reset() between pages to clear all registered symbols:

1
sc.Reset()

Full example: SSG pipeline

1
import (
2
    "bytes"
3
    "fmt"
4
5
    swarmicons "github.com/frostybee/go-swarm-icons"
6
    "github.com/frostybee/go-swarm-icons/lucide"
7
)
8
9
func main() {
10
    manager := swarmicons.Default("lucide", lucide.Provider())
11
    sc := swarmicons.NewSpriteCollector()
12
13
    // Register the icons needed for this page
14
    for _, name := range []string{"home", "star", "search"} {
15
        icon, err := manager.Get(name)
16
        if err != nil {
17
            continue
18
        }
19
        _, _, w, h := icon.ViewBox()
20
        vb := fmt.Sprintf("0 0 %d %d", w, h)
21
        sc.Register(fmt.Sprintf("i-lucide-%s", name), icon.Content(), vb)
22
    }
23
24
    // Render page HTML with <use> references
25
    var page bytes.Buffer
26
    page.WriteString(`<nav>`)
27
    page.WriteString(`<svg><use href="#i-lucide-home"></use></svg>`)
28
    page.WriteString(`<svg><use href="#i-lucide-search"></use></svg>`)
29
    page.WriteString(`</nav>`)
30
31
    // Generate and inject the sprite sheet
32
    sheet := sc.SpriteSheet(page.Bytes())
33
    if sheet != nil {
34
        page.Write(sheet)
35
    }
36
37
    fmt.Println(page.String())
38
39
    // Reset for the next page
40
    sc.Reset()
41
}