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 or feather).

2. Place Icons: Copy SVG files (e.g., camera.svg) into resources/svg/[icon-set-name] (e.g., resources/svg/heroicons/solid).

3. First Use Case: Render an icon in Blade:

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

   Or use the @svg directive:

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

4. Verify: Check the icon search tool for available icons in your chosen set.

Implementation Patterns

Core Workflows

1. Icon Rendering:

   • Component Syntax: <x-icon-[name] /> (e.g., <x-icon-user />).

     <x-icon-user class="text-blue-500" />
     

   • Directive Syntax: @svg('icon-name', 'classes').

     @svg('user', 'text-blue-500 w-8')
     

   • Dynamic Icons: Use variables for icon names:

     @svg($iconName, 'w-6 h-6')
     

2. Icon Sets:

   • Switch sets in config/blade-icons.php:

     'sets' => [
         'heroicons' => [
             'path' => resource_path('svg/heroicons'),
             'prefix' => 'heroicon',
         ],
         'feather' => [
             'path' => resource_path('svg/feather'),
             'prefix' => 'feather',
         ],
     ],
     

   • Use the icon helper to specify a set:

     @svg('user', 'w-6 h-6', 'feather')
     

3. Customization:

   • Attributes: Pass any SVG attributes via the component/directive:

     <x-icon-camera fill="red" />
     @svg('camera', 'w-6 h-6', [], ['fill' => 'red'])
     

   • View Composers: Preload icons in layouts:

     // app/View/Composers/IconComposer.php
     public function compose($view) {
         $view->with('icons', ['user', 'camera']);
     }
     

     @foreach($icons as $icon)
         <x-icon-{{ $icon }} />
     @endforeach
     

4. Dynamic Icon Loading:

   • Load icons conditionally based on user roles or features:

     @auth
         <x-icon-user />
     @endauth
     

5. Integration with UI Components:

   • Use icons in buttons, tooltips, or modals:

     <button>
         <x-icon-settings class="mr-2" />
         Settings
     </button>
     

6. Icon Packs:

   • Install third-party packs (e.g., blade-heroicons) for extended icon libraries:

     composer require blade-ui-kit/blade-heroicons
     

   • Configure in config/blade-icons.php:

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

Gotchas and Tips

Pitfalls

1. Missing SVG Files:

   • Error: Icon [name] not found.
   • Fix: Ensure SVGs exist in the configured path (e.g., resources/svg/[set-name]/[icon].svg). Use php artisan svg-discover to auto-discover icons (if available in newer versions).

2. Caching Issues:

   • Error: Icons not updating after changes.
   • Fix: Clear Blade cache:

     php artisan view:clear
     

   • For persistent issues, clear config cache:

     php artisan config:clear
     

3. Case Sensitivity:

   • Icons are case-sensitive. Use the exact filename (e.g., camera.svg not Camera.svg).

4. Namespace Conflicts:

   • Avoid naming conflicts with existing Blade components. Prefix custom icons if needed:

     <x-myapp-icon-camera />
     

5. Large Icon Sets:

   • Performance impact with hundreds of icons. Use lazy-loading or split icon sets by feature/module.

Debugging Tips

1. Verify Icon Paths:

   • Check config/blade-icons.php for correct path and prefix values. Example:

     'heroicons' => [
         'path' => resource_path('svg/heroicons/solid'),
         'prefix' => 'heroicon-solid',
     ],
     

2. Inspect SVG Output:

   • Use browser dev tools to verify rendered SVG markup. Look for missing viewBox or fill attributes.

3. Log Missing Icons:

   • Add a debug directive to log missing icons:

     @php
         if (!Icon::exists('unknown-icon')) {
             \Log::warning('Icon not found: unknown-icon');
         }
     @endphp
     

4. Custom SVG Handling:

   • Override default SVG rendering by publishing the view:

     php artisan vendor:publish --tag=blade-icons-views
     

   • Modify resources/views/vendor/blade-icons/icon.blade.php.

Extension Points

1. Custom Icon Sets:

   • Create a new set by publishing the config and adding to config/blade-icons.php:

     'custom-set' => [
         'path' => resource_path('svg/custom'),
         'prefix' => 'custom',
     ],
     

   • Use the @svg directive with the custom set:

     @svg('my-icon', 'w-6 h-6', 'custom')
     

2. Dynamic Icon Generation:

   • Extend the package to generate icons from a database or API:

     // app/Helpers/IconHelper.php
     public static function getDynamicIcon($type) {
         $svg = Icon::get("{$type}-icon");
         return str_replace('currentColor', '#4A5568', $svg);
     }
     

     {!! IconHelper::getDynamicIcon('user') !!}
     

3. Icon Animation:

   • Animate SVGs using CSS or JavaScript. Example:

     <x-icon-spinner class="animate-spin" />
     

     @keyframes spin {
         to { transform: rotate(360deg); }
     }
     .animate-spin {
         animation: spin 1s linear infinite;
     }
     

4. Accessibility:

   • Add ARIA labels to icons for screen readers:

     <x-icon-search aria-label="Search" />
     

   • Use the aria-hidden attribute for decorative icons:

     <x-icon-logo aria-hidden="true" />
     

5. Dark Mode Support:

   • Use CSS variables or Tailwind’s dark mode for adaptive icons:

     <x-icon-moon class="dark:text-yellow-300" />
     

     .dark .icon-dark { filter: invert(1); }
     

6. Icon Optimization:

   • Minify SVGs using tools like SVGO before adding them to your project.

Configuration Quirks

1. Default Set:

   • Always define a default set in config/blade-icons.php to avoid runtime errors:

     'default' => 'heroicons',
     

2. Prefix Handling:

   • Prefixes are used to generate Blade component names. Ensure consistency:
     • prefix: 'heroicon' → <x-icon-heroicon-user />
     • prefix: 'feather' → <x-icon-feather-user />

3. Path Validation:

   • The package validates paths during configuration loading. Ensure directories exist:

     mkdir -p resources/svg/heroicons/solid
     

4. Environment-Specific Configs:

   • Use Laravel’s environment configs to switch icon sets per environment:

     'sets' => env('ICON_SET') === 'production'
         ? ['heroicons' => [...]]
         : ['feather' => [...]],