Skip to main content
go-swarm-icons
On this page

Aliases & Fallbacks

Map shorthand icon names to real targets and configure fallback icons for failed lookups.

Aliases map shorthand names to frequently used icons, and fallbacks provide graceful handling when an icon is missing.

Defining aliases

An alias maps one name to another. When the manager resolves the alias, it substitutes the target name before any further resolution.

Via Config builder

Go
import swarmicons "github.com/frostybee/go-swarm-icons"
manager, _ := swarmicons.NewConfig().
    AddProvider("lucide", lucide.Provider()).
    AddProvider("heroicons", heroiconsProvider).
    DefaultPrefix("lucide").
    Alias("check", "heroicons:check-circle").
    Alias("h", "lucide:home").
    Build()
icon, _ := manager.Get("check") // resolves as "heroicons:check-circle"
icon, _ = manager.Get("h")      // resolves as "lucide:home"

Via manager method

Go
import swarmicons "github.com/frostybee/go-swarm-icons"
manager := swarmicons.Default("lucide", lucide.Provider())
manager.SetAlias("h", "lucide:home")
icon, _ := manager.Get("h") // resolves as "lucide:home"

Aliases are resolved once before name parsing. The target can include a prefix ("heroicons:check-circle") or be a bare name that uses the default prefix.

Resolution flow

When manager.Get(name) is called, the name is resolved through six stages: alias substitution, prefix parsing, provider lookup, icon retrieval, fallback chain, and attribute rendering. Aliases and fallbacks affect stages 1, 4, and 5. For the complete resolution flow with implementation details, see Architecture.

Fallback icons

Global fallback

Set a fallback icon returned whenever any requested icon is not found:

Go
import swarmicons "github.com/frostybee/go-swarm-icons"
manager, _ := swarmicons.NewConfig().
    AddProvider("lucide", lucide.Provider()).
    DefaultPrefix("lucide").
    FallbackIcon("lucide:help-circle").
    Build()
icon, _ := manager.Get("nonexistent") // returns the help-circle icon

Or on an existing manager:

Go
manager.SetFallbackIcon("lucide:help-circle")

Per-prefix fallback

Set a fallback that applies only when an icon from a specific prefix is not found. Per-prefix fallbacks take priority over the global fallback:

Go
import swarmicons "github.com/frostybee/go-swarm-icons"
manager, _ := swarmicons.NewConfig().
    AddProvider("lucide", lucide.Provider()).
    AddProvider("heroicons", heroiconsProvider).
    DefaultPrefix("lucide").
    FallbackIcon("lucide:help-circle").
    FallbackIconForPrefix("heroicons", "heroicons:question-mark-circle").
    Build()
// Missing heroicons icon → uses heroicons:question-mark-circle (per-prefix)
icon, _ := manager.Get("heroicons:nonexistent")
// Missing lucide icon → uses lucide:help-circle (global)
icon, _ = manager.Get("lucide:nonexistent")

Or on an existing manager:

Go
manager.SetFallbackIconForPrefix("heroicons", "heroicons:question-mark-circle")

Recursion guard

If the fallback icon itself is not found, the manager does not loop. It returns ErrIconNotFound (or an empty icon if IgnoreNotFound is enabled).

Go
manager.SetFallbackIcon("lucide:also-missing")
_, err := manager.Get("lucide:nonexistent")
// err wraps ErrIconNotFound (fallback was also missing)

Ignoring missing icons

IgnoreNotFound() causes Get() to return an empty *Icon with no error instead of ErrIconNotFound. This applies to both missing icons and unknown prefixes:

Go
import swarmicons "github.com/frostybee/go-swarm-icons"
manager, _ := swarmicons.NewConfig().
    AddProvider("lucide", lucide.Provider()).
    DefaultPrefix("lucide").
    IgnoreNotFound().
    Build()
icon, err := manager.Get("nonexistent")
// err is nil, icon.IsEmpty() is true
icon, err = manager.Get("unknown-prefix:anything")
// err is nil, icon.IsEmpty() is true

Or on an existing manager:

Go
manager.SetIgnoreNotFound(true)

Name parsing edge cases

Input Result
"" (empty string) ErrInvalidIconName
":home" (empty prefix) ErrInvalidIconName
"lucide:" (empty name) ErrInvalidIconName
"home" (no colon, no default prefix) ErrInvalidIconName
"home" (no colon, default prefix set) Resolves as "{defaultPrefix}:home"
"lucide:home" Prefix "lucide", name "home"

See also

Edit this page

Last updated: