Blade Icons Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require blade-ui-kit/blade-icons
   

   Publish the config (optional):

   php artisan vendor:publish --provider="BladeUI\Icons\IconsServiceProvider"
   

2. First Use Case: Register an icon set (e.g., Heroicons) in config/blade-icons.php:

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

   Use the directive in a Blade view:

   @svg('heroicons/solid/camera', ['class' => 'w-6 h-6'])
   

3. Quick Start: For a single icon, use the @svg directive:

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

   Requires the camera.svg file in the default resources/svg directory.

Implementation Patterns

Icon Registration & Organization

• Register Multiple Sets:

  // config/blade-icons.php
  'sets' => [
      'heroicons' => ['path' => 'vendor/.../heroicons', 'prefix' => 'heroicon'],
      'feather'   => ['path' => 'vendor/.../feather', 'prefix' => 'feather'],
  ],
  

  Use them in Blade:

  @svg('heroicons/solid/camera')
  @svg('feather/camera')
  

• Custom Icon Sets: Place SVGs in resources/svg/custom and register:

  'custom' => ['path' => 'resources/svg/custom', 'prefix' => 'custom'],
  

  Use:

  @svg('custom/my-icon')
  

Blade Components (Recommended)

1. Generate Components:

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

   This creates app/View/Components/Icons/ with pre-built components (e.g., Camera.php).

2. Use Components:

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

   Customize via component class:

   // app/View/Components/Icons/Camera.php
   public function class($class)
   {
       return $this->withAttributes(['class' => $class]);
   }
   

Dynamic Icons

• Pass Attributes Dynamically:

  @svg('camera', ['class' => $dynamicClass, 'fill' => $color])
  

• Conditional Icons:

  @svg($isActive ? 'check-circle' : 'x-circle')
  

Icon Management

• List Available Icons:

  php artisan icons:list
  

  Outputs all registered icons with paths.

• Search Icons:

  php artisan icons:search camera
  

Gotchas and Tips

Common Pitfalls

1. Missing SVG Files:

   • Ensure SVG files exist in the registered paths. Use php artisan icons:list to verify.
   • Default path: resources/svg/ for unregistered icons.

2. Case Sensitivity:

   • Blade directives (@svg) and component names are case-sensitive.
   • Example: @svg('Camera') fails if the file is camera.svg.

3. Caching Issues:

   • Clear Blade cache after adding new icon sets:

     php artisan view:clear
     

4. Component Autoloading:

   • If components aren’t found, ensure the app/View/Components/Icons/ directory exists and is autoloaded. Run:

     composer dump-autoload
     

Debugging Tips

• Check Registered Sets:

  // In a route or tinker
  dd(config('blade-icons.sets'));
  

• Verify SVG Paths: Use php artisan icons:list to confirm paths. For custom sets, ensure the path in config/blade-icons.php is correct.

• Directive Not Working: Ensure the @svg directive is enabled in config/blade-icons.php:

  'directive' => true,
  

Performance & Best Practices

1. Inline SVG vs. Components:

   • Use @svg for one-off icons; components (<x-icon-* />) for reusability and consistency.

2. Optimize SVG Files:

   • Minify SVGs before adding them to your project to reduce bundle size.

3. Lazy-Loading:

   • For large icon sets, consider lazy-loading components or using JavaScript to load icons on demand.

4. Extending the Package:

   • Custom Directives: Extend the @svg directive by publishing and modifying the BladeIconsServiceProvider.
   • Icon Metadata: Add metadata (e.g., categories, tags) to SVGs by extending the Icon class or using a custom resolver.

Advanced Usage

• Dynamic Icon Sets: Register sets dynamically in a service provider:

  Icons::addSet('dynamic', [
      'path' => storage_path('app/icons'),
      'prefix' => 'dynamic',
  ]);
  

• Icon Fallbacks: Provide fallback icons for missing SVGs:

  @svg($iconName, ['class' => 'w-6 h-6', 'fallback' => 'x-circle'])
  

  (Requires custom directive logic or a wrapper component.)

• Icon Theming: Use CSS variables or inline styles to theme icons dynamically:

  @svg('camera', [
      'class' => 'text-primary',
      'style' => "color: var(--icon-color)"
  ])