ArtisanPack UI Icons

An extensibility layer for custom icon sets that integrates seamlessly with blade-ui-kit/blade-icons and livewire-ui-components. This package provides a simple, flexible way to register and use custom SVG icon sets in your Laravel applications without the overhead of hardcoded icon libraries.

Features

• Zero Hardcoded Icons: No memory-heavy icon arrays - bring your own icons
• Seamless Integration: Built on blade-ui-kit/blade-icons foundation
• Dual Registration System: Configure via config files or register programmatically via events
• Third-Party Extensible: Other packages can register icon sets via event hooks
• Font Awesome Pro Ready: Easy integration with Font Awesome Pro and other premium icon sets
• Performance Optimized: Minimal memory footprint and fast loading

Installation

Install the package via Composer:

composer require artisanpack-ui/icons

Publish the configuration file:

php artisan vendor:publish --tag=artisanpack-package-config

Quick Start

1. Configure Your Icon Sets

Edit config/artisanpack/icons.php to register your icon sets:

return [
    'sets' => [
        'fa' => [
+            'path' => resource_path('icons/fontawesome-pro'),
+            'prefix' => 'fa',
+        ],
+        'brand' => [
+            'path' => resource_path('icons/custom-brand'),
+            'prefix' => 'brand',
+        ],
    ],
];

2. Organize Your Icons

Place your SVG files in the configured directories:

resources/
├── icons/
│   ├── fontawesome-pro/
│   │   ├── home.svg
│   │   └── user.svg
│   └── custom-brand/
│       ├── logo.svg
│       └── badge.svg

3. Use Icons in Blade Templates

{{-- Using Font Awesome Pro icons with 'fa' prefix --}}
<x-icon-fa-home class="w-6 h-6" />
<x-icon-fa-user class="w-5 h-5 text-blue-500" />

{{-- Using custom brand icons with 'brand' prefix --}}
<x-icon-brand-logo class="w-8 h-8" />
<x-icon-brand-badge class="w-4 h-4" />

Registration Methods

Config-Based Registration

The simplest approach - define icon sets in your config/artisanpack/icons.php:

return [
    'sets' => [
        'hero' => [
            'path'   => resource_path('icons/heroicons'), 
            'prefix' => 'hero'
        ],
+       'tabler' => [
            'path'   => resource_path('icons/tabler'),
            'prefix' => 'tabler'
        ],
    ],
];

Event-Driven Registration

Perfect for packages that want to register their own icon sets:

use ArtisanPackUI\Icons\Registries\IconSetRegistration;

// In a service provider or event listener
addFilter('ap.icons.registerIconSets', function (IconSetRegistration $registry) {
    $registry->addSet(__DIR__ . '/../../resources/icons', 'mypackage');
    return $registry;
});

Note: In v2.2.0 the hook was renamed from ap.icons.register-icon-sets to ap.icons.registerIconSets to align with the cross-package hooks naming convention. The old name is registered as a temporary deprecation alias — existing subscribers continue firing but emit an info-level deprecation log. The alias will be removed in the next major release.

Documentation

For comprehensive documentation, visit the docs directory:

Getting Started

• Installation Guide - Complete setup instructions
• Usage Examples - Practical implementation examples
• Architecture Overview - How the extensibility layer works

Advanced Usage

• Extension API - Third-party package integration
• Migration Guide - Upgrading from v1.x
• Deprecation Strategy - v1.x support timeline and migration assistance
• Service Provider - Laravel integration details

Requirements

• PHP 8.2 or higher (PHP 8.3+ required for Laravel 13)
• Laravel 12.x or 13.x
• blade-ui-kit/blade-icons ^1.8

Contributing

As an open source project, this package is open to contributions from anyone. Please read through the contributing guidelines to learn more about how you can contribute to this project.