Chain Provider

Sometimes icons come from more than one source. The chain provider wraps multiple providers in priority order and returns the first match, so local overrides take precedence over remote fallbacks.

What it does

ChainProvider wraps an ordered list of providers and returns the first match. It lets multiple icon sources act as a single provider with fallback behavior.

When to use it

Reach for a chain when the project needs local overrides on top of a remote source, or when combining multiple icon sets under a single prefix. The most common pattern is a directory of custom SVGs backed by the Iconify API for everything else.

For single-source providers, see Directory Provider, JSON Collection Provider, or Iconify Provider.

Setup

Direct construction

1
import swarmicons "github.com/frostybee/go-swarm-icons"
2
3
dirP, err := swarmicons.NewDirectoryProvider("./heroicons")
4
if err != nil {
5
    log.Fatal(err)
6
}
7
iconifyP := swarmicons.NewIconifyProvider("heroicons")
8
9
chain := swarmicons.NewChainProvider(dirP, iconifyP)
10
manager := swarmicons.Default("heroicons", chain)

The directory provider is checked first. If it has the icon, the Iconify provider is never called.

Config builder with AddHybridSet

The AddHybridSet shortcut creates a ChainProvider combining a DirectoryProvider and an IconifyProvider under a single prefix:

1
import swarmicons "github.com/frostybee/go-swarm-icons"
2
3
manager, err := swarmicons.NewConfig().
4
    AddHybridSet("heroicons", "./heroicons").
5
    DefaultPrefix("heroicons").
6
    Build()

This is equivalent to the manual chain above, but constructed internally during Build().

Options & behavior

Resolution order

Get() iterates the provider list in order and returns the first icon found. If no provider has the icon, it returns (nil, false).

1
Chain[DirectoryProvider, IconifyProvider]
2
3
Get("home"):
4
  1. DirectoryProvider.Get("home") → found? return it
5
  2. IconifyProvider.Get("home")   → found? return it
6
  3. not found → (nil, false)

Has() short-circuits

Has() returns true as soon as any provider in the chain reports the icon exists. It does not query remaining providers.

All() deduplicates

All() returns the union of all providers' icon names, deduplicated. Names appear in the order they are first encountered (first provider's names first, then new names from subsequent providers).

No internal caching

The chain provider does not cache results itself. Each wrapped provider manages its own cache. Repeated Get() calls on the chain still benefit from each provider's internal caching.

Constructor

NewChainProvider copies the provider slice. Modifying the original slice after construction has no effect on the chain.

Examples

Local overrides with remote fallback

1
import (
2
    "fmt"
3
    "log"
4
5
    swarmicons "github.com/frostybee/go-swarm-icons"
6
)
7
8
func main() {
9
    // Local directory with a few custom overrides
10
    dirP, err := swarmicons.NewDirectoryProvider("./overrides/heroicons")
11
    if err != nil {
12
        log.Fatal(err)
13
    }
14
15
    // Iconify API as the fallback for icons not in the directory
16
    iconifyP := swarmicons.NewIconifyProvider("heroicons")
17
18
    chain := swarmicons.NewChainProvider(dirP, iconifyP)
19
    manager := swarmicons.Default("heroicons", chain)
20
21
    // "home" resolves from disk if ./overrides/heroicons/home.svg exists,
22
    // otherwise from the Iconify API.
23
    icon, err := manager.Get("home")
24
    if err != nil {
25
        log.Fatal(err)
26
    }
27
    fmt.Println(icon.ToHTML())
28
}

Config builder shortcut

1
import (
2
    "fmt"
3
    "log"
4
5
    swarmicons "github.com/frostybee/go-swarm-icons"
6
    "github.com/frostybee/go-swarm-icons/lucide"
7
)
8
9
func main() {
10
    manager, err := swarmicons.NewConfig().
11
        AddProvider("lucide", lucide.Provider()).
12
        AddHybridSet("heroicons", "./heroicons").
13
        DefaultPrefix("lucide").
14
        Build()
15
    if err != nil {
16
        log.Fatal(err)
17
    }
18
19
    // Lucide icon via default prefix
20
    home, _ := manager.Get("home")
21
    fmt.Println(home.ToHTML())
22
23
    // Heroicons via explicit prefix (directory checked first, then Iconify)
24
    check, _ := manager.Get("heroicons:check-circle")
25
    fmt.Println(check.ToHTML())
26
}

Choosing a provider

See also

• Providers API reference: full ChainProvider constructor and resolution semantics
• Directory Provider: the most common first provider in a chain
• Iconify Provider: the most common fallback provider in a chain