Sprite Collector

The SpriteCollector type for building shared SVG sprite sheets from registered icon symbols.

Overview

SpriteCollector accumulates SVG icon symbols during a render pass and produces a hidden sprite sheet for injection into page HTML. It is thread-safe and designed for concurrent use across multiple goroutines.

Types

SpriteCollector

1
type SpriteCollector struct {
2
    // unexported fields
3
}

Internally stores a sync.RWMutex-protected map of symbol IDs to their body content and viewBox values.

Functions

NewSpriteCollector

1
func NewSpriteCollector() *SpriteCollector

Returns a ready-to-use collector with an empty symbol map.

Methods

Register

1
func (sc *SpriteCollector) Register(id, body, viewBox string)

Stores a symbol under id. First write wins: calling Register again with the same id is a no-op.

The id should follow the "i-{prefix}-{name}" convention (e.g., "i-lucide-home").

ID namespacing: internal SVG references in body are automatically suffixed to prevent collisions in the combined sprite sheet. The suffix is derived from the id by stripping the "i-" prefix. Affected patterns:

SpriteSheet

1
func (sc *SpriteCollector) SpriteSheet(pageHTML []byte) []byte

Scans pageHTML for <use href="#i-..."> and <use xlink:href="#i-..."> references. Looks up each referenced ID in the registered symbols. Returns a hidden <svg> element containing one <symbol> per unique matched reference, sorted by ID.

The output markup:

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>

Returns nil if no matching references are found in pageHTML, or if none of the referenced IDs have been registered.

Duplicate references in the page produce only one <symbol>.

Reset

1
func (sc *SpriteCollector) Reset()

Clears all registered symbols. Use between pages in a static site build to avoid accumulating symbols from previous renders.

Thread safety

SpriteCollector is protected by a sync.RWMutex. Register acquires a write lock. SpriteSheet acquires a read lock. Multiple goroutines can call Register and SpriteSheet concurrently.

See also

• Sprite Sheets: step-by-step guide with SSG pipeline examples
• Icon API reference: Content() and ViewBox() methods used when registering symbols