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

2. Place SVGs:

   • Copy SVG files (e.g., camera.svg) into resources/svg/[icon-set]/ (e.g., resources/svg/heroicons/).
   • Ensure filenames match the icon names (e.g., camera.svg → <x-icon-camera />).

3. First Use Case: Replace raw SVG markup in Blade:

   <!-- Before -->
   <svg ...>...</svg>
   
   <!-- After -->
   <x-icon-camera class="w-6 h-6" />
   

   Or use the @svg directive:

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

Where to Look First

• Configuration: config/blade-icons.php (define default and sets).
• Icon Search: blade-ui-kit.com/blade-icons#search for available icons.
• Documentation: GitHub README and Upgrade Guide.

Implementation Patterns

Core Workflows

1. Component-Based Usage:

   <!-- Auto-generated component -->
   <x-icon-[name] class="text-blue-500" />
   

   • Pros: Intellisense support, reusable, and clean syntax.
   • Tip: Use php artisan vendor:publish --tag=blade-icons:views to customize component templates.

2. Directive-Based Usage:

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

   • Use Case: Dynamic icon rendering (e.g., in loops or conditionals).
   • Example:

     @foreach($icons as $icon)
         @svg($icon, ['class' => 'w-5 h-5'])
     @endforeach
     

3. Custom Icon Sets:

   • Add a new set in config/blade-icons.php:

     'sets' => [
         'heroicons' => resource_path('svg/heroicons'),
         'custom' => resource_path('svg/custom'),
     ],
     

   • Place SVGs in resources/svg/custom/ and use:

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

4. Dynamic Attributes:

   <x-icon-camera :class="$isActive ? 'text-green-500' : 'text-gray-500'" />
   

   • Tip: Use @class directive for dynamic classes:

     @svg('camera', ['class' => $isActive ? 'text-green-500' : 'text-gray-500'])
     

Integration Tips

• Tailwind CSS: Leverage utility classes (e.g., w-6 h-6) directly in Blade.
• Dark Mode: Use dark: variants or inline styles:

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

• Accessibility: Add aria-hidden="true" or role="img" to SVG components.
• Lazy Loading: Combine with Alpine.js or JavaScript to load icons dynamically:

  <div x-data="{ showIcon: false }" @mouseover="showIcon = true">
      <x-icon-settings x-show="showIcon" class="w-4 h-4" />
  </div>
  

Gotchas and Tips

Pitfalls

1. Missing SVG Files:

   • Error: Class 'App\View\Components\IconCamera' not found.
   • Fix: Ensure SVGs exist in the configured path (e.g., resources/svg/heroicons/camera.svg).
   • Debug: Run php artisan cache:clear and check storage/logs/laravel.log.

2. Caching Issues:

   • Problem: Changes to SVGs or config aren’t reflected.
   • Solution:

     php artisan view:clear
     php artisan cache:clear
     

3. Namespace Conflicts:

   • Issue: Custom components clash with Blade Icons.
   • Fix: Prefix custom components (e.g., App\View\Components\CustomIcon).

4. SVG Optimization:

   • Warning: Large SVGs bloat your assets.
   • Tip: Use tools like SVGO to optimize SVGs before adding them.

Debugging

• Check Registered Icons:

  // In a route or Tinker
  \BladeUI\Icons\Facades\BladeIcon::getIconSets();
  

• Verify Config:

  php artisan config:clear
  

• Log Missing Icons: Add this to AppServiceProvider:

  Blade::if('svg', function ($expression) {
      list($name, $classes, $set) = $expression;
      if (!file_exists(resource_path("svg/{$set}/{$name}.svg"))) {
          Log::warning("Icon not found: {$set}/{$name}");
      }
      return true;
  });
  

Extension Points

1. Custom Directives: Extend the @svg directive in AppServiceProvider:

   Blade::directive('icon', function ($expression) {
       list($name, $classes, $set = config('blade-icons.default')) = $expression;
       return "<x-icon-{$name} class=\"{$classes}\" />";
   });
   

   Usage:

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

2. Icon Set Validation: Override validation in AppServiceProvider:

   \BladeUI\Icons\Facades\BladeIcon::macro('validateIcon', function ($name, $set) {
       if (!file_exists(resource_path("svg/{$set}/{$name}.svg"))) {
           throw new \InvalidArgumentException("Icon {$name} not found in set {$set}");
       }
   });
   

3. Dynamic Icon Sets: Fetch icon sets dynamically (e.g., from a database):

   config(['blade-icons.sets' => [
       'dynamic' => storage_path('app/svg/dynamic'),
   ]]);
   

Performance Tips

• Precompile Icons: Use Laravel Mix to inline critical SVGs:

  // mix.js
  const svgLoader = require('laravel-mix-svg-loader');
  mix.svgLoader();
  

• Lazy-Load Icon Sets: Load non-critical icon sets via JavaScript:

  <div x-data="{ loaded: false }">
      <template x-if="!loaded">
          <script src="/js/load-icons.js" x-on:load="loaded = true"></script>
      </template>
      <x-icon-custom x-show="loaded" />
  </div>
  

Configuration Quirks

• Default Set: Always define a default set in config/blade-icons.php to avoid runtime errors.
• Case Sensitivity: Icon filenames are case-sensitive (e.g., Camera.svg ≠ camera.svg).
• Reserved Names: Avoid names conflicting with Laravel/Blade keywords (e.g., if, else, component).