Getting Started

Minimal Setup

Installation:

composer require archielite/laravel-heroicons

Publish the config (optional, for customization):

php artisan vendor:publish --provider="Archielite\Heroicons\HeroiconsServiceProvider" --tag="heroicons-config"

First Use Case: Render a Heroicon directly in a Blade template:
```
<x-heroicon name="home" class="h-6 w-6 text-blue-500" />
```
- Replace home with any Heroicons name (e.g., bell, cog, user).
Where to Look First:
- Blade Components: Check resources/views/vendor/heroicons/ for default templates.
- Config File: config/heroicons.php for custom icon sets or paths.
- Documentation: Run php artisan heroicons:docs (if available) or browse the Heroicons website.

Implementation Patterns

Core Workflows

Dynamic Icon Selection: Use a variable to switch icons dynamically:

@php
  $icon = request()->routeIs('dashboard') ? 'home' : 'cog';
@endphp
<x-heroicon name="{{ $icon }}" class="h-5 w-5" />

Icon Sets: Heroicons provides Outline, Solid, and Mini sets. Specify the set in the component:
```
<x-heroicon name="user" set="solid" class="h-6 w-6" />
```
- Default set is outline (configurable in heroicons.php).
Integration with Tailwind CSS: Leverage Tailwind’s utility classes for styling:
```
<x-heroicon name="check-circle" class="h-6 w-6 text-green-500" />
```

Custom Icon Paths: Override default icon paths in config/heroicons.php:

'paths' => [
    'outline' => 'path/to/custom/outline-icons',
    'solid'   => 'path/to/custom/solid-icons',
],

Reusable Components: Create wrapper components for consistency:

<!-- resources/views/components/icon.blade.php -->
<x-heroicon name="{{ $name }}" set="{{ $set ?? 'outline' }}" class="h-5 w-5 {{ $classes }}" />

Usage:

<x-icon name="bell" classes="text-gray-500" />

Form Buttons: Combine with Laravel Collective or Livewire for interactive elements:

<button type="submit">
    <x-heroicon name="paper-airplane" class="h-5 w-5 mr-2" />
    Submit
</button>

Gotchas and Tips

Pitfalls

Case Sensitivity: Heroicon names are case-sensitive (e.g., home ≠ Home). Use the exact name from Heroicons.
Missing Icons: If an icon fails to render, verify:
- The name attribute matches a valid Heroicon (e.g., user exists, but user-icon does not).
- The icon set (outline, solid, mini) is correct and the corresponding SVG file exists in the package’s assets.
Caching Issues: After updating the package, clear Blade cache:
```
php artisan view:clear
```
Custom Paths: If overriding icon paths, ensure the new paths contain SVG files with the exact Heroicons filenames (e.g., home.svg for the home icon).

Debugging

Inspect the Rendered HTML: Check if the SVG is loaded correctly. Missing icons may appear as broken image placeholders.
```
@dd(\Archielite\Heroicons\Facades\Heroicons::getIcon('home', 'outline'))
```
(Use dd() to debug the raw SVG output.)
Check Config: Verify config/heroicons.php for typos in paths or sets.

Tips

Icon Size Consistency: Use Tailwind’s spacing scale (e.g., h-4 w-4, h-6 w-6) for consistent sizing across projects.

Dark Mode: Combine with Tailwind’s dark mode classes:

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

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

<x-heroicon name="chevron-down" class="h-5 w-5" aria-hidden="true" />

Performance: Preload critical icons in your layout:
```
@preloadHeroicons(['home', 'bell', 'cog'])
```
(If the package supports preloading; otherwise, manually preload SVGs.)

Extending the Package:

Add Custom Icons: Place SVGs in public/vendor/heroicons/custom/ and update config/heroicons.php:
```
'paths' => [
    'custom' => 'custom-icons',
],
```

Create a Macro: Extend the facade for project-specific shortcuts:

\Archielite\Heroicons\Facades\Heroicons::macro('alert', function () {
    return $this->icon('exclamation-circle', 'solid', 'h-6 w-6 text-red-500');
});