Blade Iconpark Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require codeat3/blade-iconpark
   

   Publish the config (if needed):

   php artisan vendor:publish --provider="Codeat3\BladeIconpark\BladeIconparkServiceProvider"
   

2. First Use Case: Add an icon to a Blade view:

   <x-iconpark name="home" />
   

   Or with custom classes:

   <x-iconpark name="settings" class="text-blue-500" />
   

3. Where to Look First:

   • Config File: config/iconpark.php (customize icon set, default classes, etc.).
   • Blade Component Docs: Run php artisan iconpark:docs (if available) or check the GitHub README for supported icon names.
   • View Examples: Check resources/views/vendor/iconpark/ for default templates.

Implementation Patterns

Common Workflows

1. Dynamic Icons via Variables:

   @php
       $iconName = $user->role === 'admin' ? 'admin' : 'user';
   @endphp
   <x-iconpark name="{{ $iconName }}" />
   

2. Reusable Icon Components: Create a custom Blade component (e.g., resources/views/components/icon-button.blade.php):

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

   Usage:

   <x-icon-button icon="search" />
   

3. Icon Sets and Theming: Override the default icon set in config/iconpark.php:

   'icon_set' => 'outline', // Options: 'outline', 'filled', 'round'
   

   Or pass it dynamically:

   <x-iconpark name="star" set="filled" />
   

4. Integration with Tailwind CSS: Use Tailwind’s arbitrary values for dynamic sizing:

   <x-iconpark name="menu" class="w-[1.25rem] h-[1.25rem]" />
   

5. Lazy Loading Icons: Load icons only when needed (e.g., in a modal or dropdown):

   @if (request()->wantsJson())
       <x-iconpark name="spinner" class="animate-spin" />
   @endif
   

Advanced Patterns

1. Custom Icon Registration: Extend the package to register custom icons:

   // In a service provider
   BladeIconpark::registerIcon('custom-icon', 'path/to/icon.svg');
   

2. Icon-Based Navigation: Dynamically generate a sidebar menu:

   @foreach ($menuItems as $item)
       <a href="{{ route($item['route']) }}" class="flex items-center p-2">
           <x-iconpark name="{{ $item['icon'] }}" class="mr-2" />
           <span>{{ $item['label'] }}</span>
       </a>
   @endforeach
   

3. Dark Mode Support: Toggle icon variants based on theme:

   <x-iconpark
       name="moon"
       class="{{ config('theme.dark') ? 'text-yellow-300' : 'text-gray-500' }}"
   />
   

Gotchas and Tips

Pitfalls

1. Icon Name Typos:

   • The package does not throw errors for invalid icon names. Use php artisan iconpark:list (if available) or check the Icon Park docs for valid names.
   • Debug Tip: Wrap the component in @error to catch missing icons:

     @error
         <span class="text-red-500">Icon "{{ $iconName }}" not found</span>
     @enderror
     

2. Caching Issues:

   • If icons appear broken after updates, clear Blade cache:

     php artisan view:clear
     

3. SVG Optimization:

   • Large SVG files may bloat your HTML. Use the inline option to optimize:

     <x-iconpark name="graph" inline="true" />
     

4. Conflicting Class Names:

   • Avoid naming conflicts with Tailwind or other CSS frameworks. Use arbitrary values:

     <x-iconpark name="alert" class="[--iconpark-color:theme('colors.red.500')]" />
     

Debugging

1. Inspect Rendered HTML: Check the <svg> output in the browser’s dev tools to verify attributes (e.g., fill, width, height).

2. Log Missing Icons: Add a fallback in your Blade component:

   @php
       $icon = BladeIconpark::getIcon($name) ?: 'help-circle';
   @endphp
   <x-iconpark name="{{ $icon }}" />
   

3. Check Config Overrides: Ensure no other packages are modifying config/iconpark.php after your changes.

Extension Points

1. Custom Icon Sets: Override the default set by publishing the config and extending the IconSet class:

   // app/Providers/BladeIconparkServiceProvider.php
   use Codeat3\BladeIconpark\Contracts\IconSet;
   
   class CustomIconSet implements IconSet {
       public function getIcons(): array {
           return [
               'custom-icon' => 'M10 20v-6h4v6h5v-8h3L12 3 2 12h3v8z',
           ];
       }
   }
   

2. Dynamic Icon Loading: Fetch icons from an API or database:

   @foreach ($dynamicIcons as $icon)
       <x-iconpark name="{{ $icon['name'] }}" set="{{ $icon['set'] }}" />
   @endforeach
   

3. Accessibility (a11y): Add ARIA labels or titles:

   <x-iconpark name="search" aria-label="Search" title="Click to search" />
   

4. Animation Support: Animate icons with Tailwind or CSS:

   <x-iconpark name="spinner" class="animate-spin" />
   

   Or use the inline option for custom animations:

   <x-iconpark name="heart" inline="true" class="transition-colors duration-300" />