Blade Heroicons Laravel Package

Getting Started

Minimal Steps

1. Installation:

   composer require blade-ui-kit/blade-heroicons
   

   Ensure your project meets the requirements: PHP 8.0+ and Laravel 9+.

2. First Use Case: Use a Heroicon 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. Explore Icons: Browse the Heroicons website or check the resources/svg directory in the package for available icons.

Implementation Patterns

Usage Patterns

1. Component-Based Icons: Use Blade components for icons with customizable classes and attributes:

   <!-- Outline icon -->
   <x-heroicon-o-check-circle class="w-5 h-5 text-green-500" />
   
   <!-- Solid icon -->
   <x-heroicon-s-check-circle class="w-5 h-5 text-green-500" />
   
   <!-- Mini icon -->
   <x-heroicon-m-check-circle class="w-4 h-4 text-green-500" />
   
   <!-- Micro icon -->
   <x-heroicon-c-check-circle class="w-3 h-3 text-green-500" />
   

2. Dynamic Icons with @svg Directive: Use the @svg directive for dynamic icon selection:

   @svg($iconName, 'w-6 h-6', ['class' => 'text-blue-500'])
   

   Pass $iconName dynamically from your controller or logic.

3. Global Configuration: Publish the config file for default classes/attributes:

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

   Customize defaults in config/blade-heroicons.php:

   'default_classes' => 'w-5 h-5',
   'default_attributes' => ['fill' => 'currentColor'],
   

4. Raw SVG Assets: Publish SVG files for direct use in assets:

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

   Use in Blade:

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

Workflows

1. Icon Selection Workflow:

   • Identify the icon name from Heroicons.
   • Use the appropriate prefix (o-, s-, m-, c-) in Blade.
   • Apply Tailwind CSS classes (e.g., w-6 h-6) for sizing and styling.

2. Dynamic Icon Rendering:

   • Store icon names in your database or config.
   • Pass the name to the @svg directive:

     @svg($dynamicIconName, 'w-5 h-5', ['class' => 'text-' . $color])
     

3. Component Integration: Create reusable components that include Heroicons:

   @component('components.button')
     <x-heroicon-o-arrow-left class="mr-2" />
     Back
   @endcomponent
   

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

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

Integration Tips

1. Tailwind CSS: Leverage Tailwind’s utility classes for consistent icon styling:

   <x-heroicon-o-bell class="w-6 h-6 text-gray-500 hover:text-blue-500" />
   

2. Accessibility: Add aria-hidden="true" for decorative icons:

   <x-heroicon-o-arrow-right aria-hidden="true" class="w-5 h-5" />
   

3. Icon Caching: Enable Blade Icons caching for performance:

   php artisan config:cache
   php artisan view:cache
   

4. Testing: Test icons in isolation using Laravel’s Blade testing helpers:

   $this->blade('<x-heroicon-o-check-circle />')->assertSeeText('check-circle');
   

Gotchas and Tips

Pitfalls

1. Icon Naming:

   • Gotcha: Heroicons use hyphenated names (e.g., arrow-left), but some older versions may use underscores (e.g., arrow_left). Always refer to the Heroicons website for the latest naming conventions.
   • Fix: Use the @svg directive with dynamic names to avoid hardcoding:

     @svg('heroicon-o-arrow-left', 'w-5 h-5')
     

2. Caching Issues:

   • Gotcha: After publishing config or SVG files, clear Blade cache:

     php artisan view:clear
     

   • Fix: Use --force when publishing to overwrite existing files.

3. Laravel Version Mismatch:

   • Gotcha: The package supports Laravel 9+, but some features (e.g., config publishing) may behave differently in older versions.
   • Fix: Check the changelog for version-specific notes.

4. SVG Asset Paths:

   • Gotcha: Published SVG files are stored in public/vendor/blade-heroicons/. Hardcoding paths may break if the directory structure changes.
   • Fix: Always use asset() helper:

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

5. Dynamic @svg Directive:

   • Gotcha: The @svg directive requires the full icon name (e.g., heroicon-o-arrow-left), not just the suffix (e.g., o-arrow-left).
   • Fix: Prepend heroicon- to dynamic icon names:

     @svg('heroicon-' . $iconSuffix, 'w-5 h-5')
     

Debugging

1. Missing Icons:

   • Debug: Check if the icon name is correct by inspecting the resources/svg directory in the package or the Heroicons website.
   • Debug: Verify Blade compilation by checking the compiled view file (e.g., storage/framework/views/).

2. Styling Not Applying:

   • Debug: Ensure Tailwind CSS is properly configured and the icon classes (e.g., w-6 h-6) are valid.
   • Debug: Use inline styles temporarily to isolate the issue:

     <x-heroicon-o-arrow-left style="width: 24px; height: 24px; color: red;" />
     

3. Performance Issues:

   • Debug: Disable Blade Icons caching temporarily to check if the issue persists:

     php artisan config:clear
     php artisan view:clear
     

   • Debug: Use browser dev tools to check if SVG files are being loaded correctly.

Tips

1. Icon Organization:

   • Group related icons in Blade components or partials:

     <!-- resources/views/components/icons/navigation.blade.php -->
     <x-heroicon-o-arrow-left class="w-5 h-5" />
     

2. Dark Mode Icons:

   • Use Tailwind’s dark mode classes for automatic adaptation:

     <x-heroicon-o-sun class="w-6 h-6 dark:hidden" />
     <x-heroicon-o-moon class="w-6 h-6 hidden dark:block" />
     

3. Custom Icon Sets:

   • Extend the package by publishing and modifying SVG files in public/vendor/blade-heroicons/.

4. Accessibility:

   • Add aria-label for interactive icons:

     <button aria-label="Notifications">
       <x-heroicon-o-bell class="w-6 h-6" />
     </button>
     

5. Version Upgrades:

   • Check the upgrade guide for breaking changes when updating the package.
   • Test thoroughly after updates, especially if using custom configurations or published SVGs.

6. Performance Optimization:

   • Enable Blade Icons caching for production:

     php artisan config:cache
     php artisan view:cache
     

   • Use micro (c-) or mini (m-) icons for smaller UI elements to reduce file size.