README

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;
use TorMorten\Eventy\Facades\Eventy;

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

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
Laravel 12.0 or higher
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.

artisanpack-ui / icons

Maintainers

Details