Custom Icon Sets

An icon set supplies the icons editors can choose in an Icon Picker field. Create a custom icon set when your project needs a collection that the built-in sets can’t provide, such as brand icons styled by your own stylesheet. These examples use a bootstrapped Craft module (opens new window) with the namespace modules\sitemodule.

Create the Icon Set Class

An icon set class extends verbb\iconpicker\base\IconSet and adds its icons in fetchIcons(). This example creates modules/sitemodule/BrandCssIconSet.php with three CSS icons. Replace the example stylesheet URL with a stylesheet you host that defines brand-icon and the three brand-icon--… classes. Your site must load the same stylesheet to render these icons publicly.

<?php
namespace modules\sitemodule;

use verbb\iconpicker\base\IconSet;
use verbb\iconpicker\models\Icon;

use Craft;

class BrandCssIconSet extends IconSet
{
    public static function displayName(): string
    {
        return Craft::t('site', 'Brand Icons');
    }

    public function fetchIcons(): void
    {
        $icons = [
            'logo',
            'mark',
            'spark',
        ];

        foreach ($icons as $icon) {
            $this->icons[] = new Icon([
                'type' => Icon::TYPE_CSS,
                'iconSetHandle' => $this->handle,
                'value' => 'brand-icon brand-icon--' . $icon,
            ]);
        }

        // Optional: tell the CP which remote stylesheet to preview with
        $this->fonts[] = [
            'type' => 'remote',
            'name' => 'Brand Icons',
            'url' => 'https://cdn.example.com/brand-icons.css',
        ];
    }
}

Each icon’s iconSetHandle identifies the set it came from, so Icon Picker can load the set’s styles for element previews and show it alongside other sets.

Register the Icon Set

Icon Picker finds icon sets through the registerIconSets event. Register your class from your module or plugin’s init() method.

use modules\sitemodule\BrandCssIconSet;
use verbb\iconpicker\events\RegisterIconSetsEvent;
use verbb\iconpicker\services\IconSets;
use yii\base\Event;

Event::on(IconSets::class, IconSets::EVENT_REGISTER_ICON_SETS, function(RegisterIconSetsEvent $event) {
    $event->iconSets[] = BrandCssIconSet::class;
});

Icons and Resources

fetchIcons() fills these properties, and Icon Picker caches the result unless the enableCache setting is off.

Test the Icon Set

Create an icon set of type Brand Icons under Icon Picker → Settings → Icon Sets, then enable it on a test Icon Picker field. Select each icon and confirm the control-panel preview appears. Save the entry and render its CSS classes on a page that loads your brand stylesheet.

Methods