Blade Icons Laravel Package

Getting Started

Minimal Steps

1. Installation:

   composer require blade-ui-kit/blade-icons
   php artisan vendor:publish --tag=blade-icons
   

   • Uncomment the default icon set in config/blade-icons.php (e.g., heroicons).
   • Place your SVG files in resources/svg (or the configured directory).

2. First Use Case:

   • Use a pre-built icon set (e.g., Heroicons):

     <x-icon-home class="w-6 h-6" />
     

   • Or register a custom icon:

     @svg('camera', 'w-6 h-6')
     

3. Where to Look First:

   • Official Documentation
   • config/blade-icons.php (configuration)
   • resources/svg (icon storage)
   • Icon Search Tool (for finding icons).

Implementation Patterns

Usage Patterns

1. Component-Based Icons:

   • Use Blade components for icons (e.g., <x-icon-home />).
   • Customize via classes or attributes:

     <x-icon-home class="w-8 h-8 text-red-500" />
     

2. Direct SVG Injection:

   • Use the @svg directive for dynamic or inline usage:

     @svg('camera', ['class' => 'w-6 h-6', 'fill' => 'currentColor'])
     

3. Dynamic Icon Selection:

   • Pass dynamic icon names via variables:

     @php($icon = 'home')
     <x-icon-{{ $icon }} class="w-6 h-6" />
     

4. Icon Sets:

   • Switch between icon sets (e.g., Heroicons, Feather, Tabler) by updating config/blade-icons.php:

     'sets' => [
         'heroicons' => [
             'path' => 'vendor/blade-ui-kit/blade-heroicons/resources/svg',
             'prefix' => 'heroicon',
         ],
     ],
     

5. Custom Icon Sets:

   • Register third-party icon sets (e.g., Bootstrap Icons):

     composer require davidhsianturi/blade-bootstrap-icons
     

     Then update config/blade-icons.php to include the new set.

6. Reusable Icon Components:

   • Create custom Blade components for complex icon usage:

     @component('icons.button', ['icon' => 'check', 'size' => 'lg'])
     @endcomponent
     

Workflows

1. Icon Discovery:

   • Use the icon search tool to find icons, then copy the SVG to resources/svg and reference it.

2. Theming:

   • Override icon colors/sizes via Tailwind or inline styles:

     <x-icon-home class="text-blue-500 dark:text-blue-400" />
     

3. Accessibility:

   • Add aria-hidden="true" or screen-reader-only text:

     <x-icon-home aria-hidden="true" />
     <span class="sr-only">Home</span>
     

4. Performance:

   • Cache icon sets during deployment (Laravel's view caching will handle Blade components).

5. Integration with UI Libraries:

   • Combine with Alpine.js for interactive icons:

     <x-icon-bell class="cursor-pointer" x-on:click="toggleNotification" />
     

Gotchas and Tips

Pitfalls

1. Missing SVG Files:

   • If an icon fails to render, verify the SVG file exists in the configured directory.
   • Check storage/logs/laravel.log for missing file errors.

2. Caching Issues:

   • Clear Blade cache after adding new icons:

     php artisan view:clear
     

   • Or disable caching temporarily for testing:

     // config/view.php
     'cache' => env('VIEW_CACHE', false),
     

3. Namespace Conflicts:

   • Avoid naming conflicts with existing Blade components (e.g., <x-icon-home> vs. <x-home-icon>).

4. Dynamic Icon Names:

   • Use {{ }} for dynamic icon names to prevent syntax errors:

     <x-icon-{{ $dynamicIcon }} />
     

5. SVG Optimization:

   • Optimize SVGs (e.g., remove metadata, simplify paths) to reduce file size and improve rendering performance.

Debugging

1. Check Icon Existence:

   • Verify the SVG file path in config/blade-icons.php matches the actual location.

2. Inspect Rendered Output:

   • Use browser dev tools to check if the SVG is loaded or if there are 404 errors.

3. Log Missing Icons:

   • Extend the package to log missing icons:

     // app/Providers/BladeIconsServiceProvider.php
     BladeIcons::missing(function ($icon) {
         Log::warning("Icon '{$icon}' not found.");
     });
     

Configuration Quirks

1. Default Icon Set:

   • Ensure the default key in config/blade-icons.php is set to an existing icon set:

     'default' => 'heroicons',
     

2. Custom Directories:

   • If using a custom directory (e.g., public/svg), update the path in the config:

     'sets' => [
         'custom' => [
             'path' => 'public/svg',
             'prefix' => 'custom-icon',
         ],
     ],
     

3. Prefix Handling:

   • The prefix in the config determines the Blade component name (e.g., heroicon-home becomes <x-icon-home>).

Extension Points

1. Custom Icon Sets:

   • Create a new icon set by publishing the config and adding a new entry:

     'my-icons' => [
         'path' => 'resources/svg/my-icons',
         'prefix' => 'my-icon',
     ],
     

   • Place SVGs in resources/svg/my-icons and use them as <x-icon-my-icon />.

2. Modify Icon Rendering:

   • Override the default SVG rendering by extending the package:

     // app/Providers/BladeIconsServiceProvider.php
     BladeIcons::macro('customSvg', function ($icon, $attributes) {
         return '<svg custom-attribute="value">' . file_get_contents(resource_path("svg/{$icon}.svg")) . '</svg>';
     });
     

     Usage:

     @customSvg('camera', ['class' => 'w-6 h-6'])
     

3. Add Icon Metadata:

   • Extend the package to include icon descriptions or categories:

     BladeIcons::extend(function ($view, $icon) {
         $metadata = collect([
             'camera' => ['category' => 'media', 'description' => 'Camera icon'],
         ]);
         $view->withIconMetadata($metadata->get($icon, []));
     });
     

     Usage:

     @php($metadata = $iconMetadata ?? [])
     <x-icon-camera title="{{ $metadata['description'] ?? '' }}" />
     

4. Lazy Loading:

   • Implement lazy loading for icons using JavaScript:

     <div class="icon-container" data-icon="camera">
         <noscript><x-icon-camera /></noscript>
     </div>
     

     JavaScript:

     document.querySelectorAll('.icon-container').forEach(el => {
         const icon = el.dataset.icon;
         el.innerHTML = `<x-icon-${icon} />`;
     });
     

5. Dark Mode Support:

   • Use Laravel Mix or Vite to compile dark-mode-specific SVGs:

     @if(config('app.dark_mode'))
         <x-icon-home-dark class="w-6 h-6" />
     @else
         <x-icon-home class="w-6 h-6" />
     @endif