Blade Heroicons Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require blade-ui-kit/blade-heroicons
   

   This adds Heroicons as Blade components and leverages Blade Icons under the hood.

2. First Use Case: Use an icon directly in a Blade view:

   <x-heroicon-o-arrow-left class="w-6 h-6 text-gray-500" />
   

   Replace o-arrow-left with any Heroicons name.

3. Key Resources:

   • Heroicons Official Site for icon previews.
   • Blade Icons Docs for advanced features (e.g., caching).

Implementation Patterns

Core Workflows

1. Component-Based Usage: Prefix Heroicons with x-heroicon- followed by the icon type (o-, s-, m-, c-) and name:

   <!-- Outline -->
   <x-heroicon-o-check-circle class="text-green-500" />
   
   <!-- Solid -->
   <x-heroicon-s-pencil class="w-5 h-5" />
   
   <!-- Mini -->
   <x-heroicon-m-home class="text-blue-600" />
   
   <!-- Micro -->
   <x-heroicon-c-bell class="text-gray-400" />
   

2. Dynamic Icons: Use Blade logic to switch icons dynamically:

   @php
     $icon = $isActive ? 'heroicon-s-check' : 'heroicon-o-x';
   @endphp
   <x-{{ $icon }} class="w-5 h-5" />
   

3. Inline Styling: Pass classes or styles directly:

   <x-heroicon-o-search
     class="w-6 h-6"
     style="color: #6b7280; transition: all 0.2s"
   />
   

4. SVG Directive: For non-component usage (e.g., in JavaScript):

   @svg('heroicon-o-arrow-left', 'w-4 h-4', ['fill' => 'currentColor'])
   

5. Raw SVG Assets: Publish and use SVGs directly:

   php artisan vendor:publish --tag=blade-heroicons --force
   

   <img src="{{ asset('vendor/blade-heroicons/o-arrow-left.svg') }}" alt="Icon" />
   

Integration Tips

1. Tailwind CSS: Combine with Tailwind for consistent sizing/colors:

   <x-heroicon-o-menu class="w-6 h-6 text-indigo-600 hover:text-indigo-800" />
   

2. Component Wrappers: Create reusable components (e.g., ButtonIcon.blade.php):

   <button class="p-2 rounded-md hover:bg-gray-100">
     <x-heroicon-o-{{ $icon }} class="w-5 h-5" />
   </button>
   

3. Icon Sets: Group related icons in a partial:

   @component('icons.user')
     <x-heroicon-o-user />
     <x-heroicon-o-cog />
   @endcomponent
   

4. Dark Mode: Use Tailwind’s dark mode classes:

   <x-heroicon-o-moon class="w-6 h-6 dark:text-gray-300" />
   

5. Accessibility: Add aria-hidden and role for non-interactive icons:

   <x-heroicon-o-info-circle
     class="w-5 h-5 text-blue-500"
     aria-hidden="true"
     role="img"
   />
   

Gotchas and Tips

Pitfalls

1. Caching:

   • Issue: Icons may not update after changes if Blade Icons caching is enabled.
   • Fix: Clear cached views:

     php artisan view:clear
     

   • Tip: Enable caching in config/blade-heroicons.php for production:

     'cache' => env('ICON_CACHE_ENABLED', true),
     

2. Icon Naming:

   • Gotcha: Heroicons use hyphenated names (e.g., arrow-left), not camelCase.
   • Fix: Use the exact name from Heroicons.

3. Laravel Version:

   • Issue: Older Laravel versions (<9.0) may not work.
   • Fix: Upgrade Laravel or use an older package version (check releases).

4. SVG Publishing:

   • Gotcha: Publishing SVGs overwrites existing files in public/vendor/blade-heroicons.
   • Fix: Use --force or back up files first.

5. Component Autoloading:

   • Issue: Custom components may not autoload if Blade Icons isn’t registered.
   • Fix: Ensure BladeIconsServiceProvider is in config/app.php.

Debugging

1. Missing Icons:

   • Check for typos in icon names.
   • Verify the icon exists in Heroicons.
   • Run php artisan view:clear if icons disappear after updates.

2. Styling Issues:

   • Use !important sparingly; Heroicons SVGs may have inline styles.
   • Inspect the compiled SVG in the browser’s dev tools.

3. Performance:

   • Tip: Cache icons in production ('cache' => true).
   • Warning: Avoid inline styles for dynamic values (e.g., style="color: {{ $color }}")—use classes instead.

Extension Points

1. Custom Icons:

   • Add new icons by extending BladeIconsServiceProvider or publishing SVGs manually.

2. Global Defaults: Configure defaults in config/blade-heroicons.php:

   'default_class' => 'w-5 h-5 text-gray-500',
   'default_attributes' => ['aria-hidden' => 'true'],
   

3. Icon Aliases: Create shortcuts in a macro:

   use BladeUI\Icons\Factory;
   BladeIcons::macro('user', fn() => 'heroicon-o-user');
   

   Usage:

   <x-heroicon-user class="w-6" />
   

4. Dynamic Icon Resolution: Override the resolver in AppServiceProvider:

   public function boot()
   {
       BladeIcons::resolveUsing(function ($icon) {
           return "custom-{$icon}";
       });
   }
   

5. Testing: Mock icons in tests:

   BladeIcons::shouldReceive('resolve')->andReturn('heroicon-o-check');