IconManager

The IconManager type coordinates resolution, aliases, fallbacks, and rendering through a single Get() entry point.

Overview

IconManager is the central registry and resolver for SVG icons. It maps prefixes to providers, resolves aliases, applies attribute rendering via IconRenderer, and handles fallback logic. All methods are safe for concurrent use.

For guides on resolution, aliases, and fallbacks, see Aliases & Fallbacks. For attribute merging, see Attribute Management.

Types

IconManager

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

Create via Default (quick start) or NewConfig().Build() (full configuration). A zero-value *IconManager is usable after calling Register.

Functions

Default

1
func Default(prefix string, provider Provider) *IconManager

Creates an IconManager with provider registered under prefix, which is also set as the default prefix. Initializes an IconRenderer with no default or prefix attributes.

1
import (
2
    swarmicons "github.com/frostybee/go-swarm-icons"
3
    "github.com/frostybee/go-swarm-icons/lucide"
4
)
5
6
manager := swarmicons.Default("lucide", lucide.Provider())

Methods

Get

1
func (m *IconManager) Get(name string, attrs ...map[string]string) (*Icon, error)

Resolves name through the full resolution flow (alias → parse → lookup → retrieve → fallback → render). The optional attrs map provides caller-level attributes at the highest precedence layer.

Returns ErrInvalidIconName for malformed names, ErrProviderNotFound for unknown prefixes, and ErrIconNotFound when the icon is not found and no fallback resolves. All errors are wrapped with the original name for context.

When IgnoreNotFound is enabled, returns an empty *Icon (no error) instead of ErrIconNotFound or ErrProviderNotFound.

Has

1
func (m *IconManager) Has(name string) bool

Reports whether name can be resolved against a registered provider. Resolves aliases and parses the prefix. Returns false for invalid names or unknown prefixes.

All

1
func (m *IconManager) All(prefix string) []string

Returns the names of every icon available in the provider registered under prefix. Returns nil if no provider is registered for that prefix.

Register

1
func (m *IconManager) Register(prefix string, p Provider) *IconManager

Adds p under prefix, replacing any existing provider for that prefix. Returns the manager for chaining. Safe to call on a zero-value *IconManager.

SetAlias

1
func (m *IconManager) SetAlias(alias, target string)

Maps alias to target so that Get(alias) resolves the same icon as Get(target). The target can include a prefix (e.g., "heroicons:check-circle").

SetDefaultPrefix

1
func (m *IconManager) SetDefaultPrefix(prefix string)

Sets the prefix applied when Get receives a bare name with no colon separator.

SetFallbackIcon

1
func (m *IconManager) SetFallbackIcon(name string)

Sets the global fallback icon name returned when a requested icon is not found. The fallback is resolved through the same flow as a normal Get call, with a recursion guard to prevent infinite loops.

SetFallbackIconForPrefix

1
func (m *IconManager) SetFallbackIconForPrefix(prefix, name string)

Sets a fallback icon name used only when an icon from prefix is not found. Checked before the global fallback.

SetIgnoreNotFound

1
func (m *IconManager) SetIgnoreNotFound(ignore bool)

Controls whether Get returns an empty *Icon (no error) instead of ErrIconNotFound or ErrProviderNotFound.

SetRenderer

1
func (m *IconManager) SetRenderer(r *IconRenderer)

Replaces the IconRenderer used for attribute merging and ARIA injection. Pass nil to disable rendering (icons are returned as-is from the provider).

See also

• Aliases & Fallbacks: practical guide to aliases, fallback icons, and IgnoreNotFound
• Config Builder: the fluent builder for constructing a fully configured IconManager