Directory Provider

Point the provider at a directory of .svg files and its icons become available by name, with lazy loading and automatic caching.

What it does

DirectoryProvider loads SVG icons from a directory on disk. Each icon is read once on first access, sanitized, and cached in memory for all subsequent calls.

When to use it

Reach for this provider when the project has its own .svg files: custom icons, brand assets, or exports from design tools. It keeps the icon source under version control and requires no network access or external data formats.

For bundled icon sets distributed as JSON, see JSON Collection Provider. For on-demand access to remote icon sets, see Iconify Provider.

Setup

Direct construction

1
import swarmicons "github.com/frostybee/go-swarm-icons"
2
3
p, err := swarmicons.NewDirectoryProvider("./icons")
4
if err != nil {
5
    // directory does not exist or is not a directory
6
    log.Fatal(err)
7
}
8
9
manager := swarmicons.Default("custom", p)
10
icon, err := manager.Get("home") // resolves ./icons/home.svg

Config builder

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

AddDirectory creates the DirectoryProvider internally during Build() and returns an error if the directory is invalid.

Options & behavior

Functional options

Pass options after the directory path in NewDirectoryProvider:

1
import swarmicons "github.com/frostybee/go-swarm-icons"
2
3
p, err := swarmicons.NewDirectoryProvider("./icons",
4
    swarmicons.WithRecursive(false),
5
    swarmicons.WithExtension("svg2"),
6
)

Recursive scanning

When recursive mode is enabled (the default), subdirectory names form part of the icon name, separated by /:

1
icons/
2
├── home.svg          → "home"
3
├── outline/
4
│   ├── home.svg      → "outline/home"
5
│   └── star.svg      → "outline/star"
6
└── solid/
7
    └── check.svg     → "solid/check"

Disable recursion with WithRecursive(false) to scan only the top-level directory.

Preloading

Preload() reads all icons from the directory into the in-memory cache upfront. This is useful for production deployments where the first-request latency of lazy loading is unacceptable.

1
import swarmicons "github.com/frostybee/go-swarm-icons"
2
3
p, err := swarmicons.NewDirectoryProvider("./icons")
4
if err != nil {
5
    log.Fatal(err)
6
}
7
p.Preload()

After Preload(), all subsequent Get() calls return cached results with no disk I/O.

Path traversal protection

The provider guards against path traversal attacks. The resolved path is checked with filepath.EvalSymlinks and must have the provider's root directory as a prefix. Any name that escapes the root returns false from both Get() and Has().

Caching

Icons are cached in a thread-safe sync.RWMutex-protected map. The read path acquires only a read lock. On a cache miss, a write lock is acquired, the icon is loaded from disk, and the result is stored. Concurrent callers racing on the same name are safe: the first to acquire the write lock stores the result, and subsequent callers return the cached value.

Error handling

NewDirectoryProvider returns an error wrapping swarmicons.ErrProviderError if the path does not exist or is not a directory. Individual Get() calls return (nil, false) for missing or unreadable files.

Examples

Minimal setup

1
import (
2
    "fmt"
3
4
    swarmicons "github.com/frostybee/go-swarm-icons"
5
)
6
7
func main() {
8
    p, err := swarmicons.NewDirectoryProvider("./icons")
9
    if err != nil {
10
        panic(err)
11
    }
12
13
    manager := swarmicons.Default("local", p)
14
    icon, err := manager.Get("home")
15
    if err != nil {
16
        panic(err)
17
    }
18
    fmt.Println(icon.ToHTML())
19
}

Recursive directory with preload

1
import (
2
    "fmt"
3
    "log"
4
5
    swarmicons "github.com/frostybee/go-swarm-icons"
6
)
7
8
func main() {
9
    p, err := swarmicons.NewDirectoryProvider("./icons",
10
        swarmicons.WithRecursive(true),
11
    )
12
    if err != nil {
13
        log.Fatal(err)
14
    }
15
    p.Preload()
16
17
    manager := swarmicons.Default("app", p)
18
19
    // Access icons from subdirectories
20
    outline, _ := manager.Get("outline/home")
21
    solid, _ := manager.Get("solid/check")
22
23
    fmt.Println(outline.ToHTML())
24
    fmt.Println(solid.ToHTML())
25
26
    // List all available icons
27
    for _, name := range manager.All("app") {
28
        fmt.Println(name)
29
    }
30
}

Choosing a provider

See also

• Providers API reference: full DirectoryProvider constructor, methods, and functional options
• JSON Collection Provider: load Iconify-format JSON sets instead of raw SVG files
• Performance & Caching: preloading, cache behavior, and throughput guidance