Using JSON Collections

This is the recommended way to use Iconify sets in production. You download the sets you need ahead of time, and Swarm Icons loads them from disk: no HTTP requests at runtime, no Node.js required.

The workflow

1. Download the sets you need

   vendor/bin/swarm-icons json:download mdi tabler heroicons

   This fetches each set as a JSON file into resources/json/. No Node.js required.

2. Auto-discover and render

   $manager = SwarmIconsConfig::create()
       ->discoverJsonSets()
       ->cachePath(__DIR__ . '/cache/icons')
       ->build();
   
   echo swarm_icon('mdi:home');
   echo swarm_icon('tabler:star');
   echo swarm_icon('heroicons:check');

   discoverJsonSets() scans resources/json/ for every .json file and registers it as a provider, using the filename as the prefix. One line covers all your downloaded sets.

Finding sets to download

Over 200 Iconify icon sets are available. Browse them from the CLI:

vendor/bin/swarm-icons json:browse
vendor/bin/swarm-icons json:browse --search=emoji

Or download all 22 popular sets at once:

vendor/bin/swarm-icons json:download --all

See Icon Set Commands for the full CLI reference.

Keeping sets in sync

Downloaded sets are recorded in a swarm-icons.json manifest at your project root. Running json:download with no arguments re-downloads everything in the manifest (handy for CI/CD or restoring after a fresh clone).

Tip

Add json:download to your Composer scripts so sets are restored automatically on composer install (useful for CI and fresh clones).

To make this automatic, add Composer scripts:

"scripts": {
    "post-install-cmd": ["swarm-icons json:download"],
    "post-update-cmd":  ["swarm-icons json:download"]
}

Think of it as npm install @iconify-json/*, but in pure PHP with a JSON manifest instead of package.json.

Other ways to register

Auto-discovery is the easiest path, but you can also register sets individually.

A specific JSON file:

->addJsonCollection('mdi', __DIR__ . '/resources/json/mdi.json')

From the iconify/json Composer package (if you’ve installed it via Composer):

->addIconifyJsonSet('mdi')       // resolves vendor/iconify/json/json/mdi.json
->addIconifyJsonSet('tabler')

A custom directory:

->discoverJsonSets('/custom/path/to/json')

Under the hood

The JSON file isn’t parsed upfront. It’s lazy-loaded on the first get() call, and individual icons are cached via PSR-16 after that. Subsequent requests never touch the JSON file again.

Aliases defined in the Iconify JSON format are resolved transparently: if the MDI set defines home-variant as an alias for home, calling swarm_icon('mdi:home-variant') just works.

When to use JSON vs. the Iconify API

	JSON Collections	Iconify API
When icons are fetched	At deploy/setup time	At runtime, on first use
Works offline	Yes	No
What you get	The whole set at once	Only the icons you use
Setup	json:download + discoverJsonSets()	addIconifySet()

For most apps, JSON collections are the better choice: icons load instantly with zero network overhead. The Iconify API is useful for prototyping or when you want access to every icon without downloading anything upfront.