Getting Started

Minimal Steps

Installation:

composer require wireui/heroicons
npm install @heroicons/tailwind  # If not already installed

Tailwind Configuration (if not already set up): Add the WireUI plugin to tailwind.config.js:
```
plugins: [
    require('wireui/tailwind'),
],
```
First Usage: Use the @heroicon directive in Blade templates:
```
@heroicon('solid/check-circle', class="h-6 w-6 text-green-500")
```
- Solid: Filled icons (e.g., solid/check-circle).
- Outline: Empty icons (e.g., outline/shopping-cart).
- Mini: Tiny variants (e.g., mini/star).

Where to Look First

Documentation: WireUI Heroicons Docs.
Icon Explorer: Heroicons Official Site (for icon names).
Blade Directives: Focus on @heroicon syntax and available variants.

First Use Case

Replace a manually added SVG icon in a Blade component (e.g., a button) with @heroicon:

<!-- Before -->
<button>
    <svg xmlns="http://www.w3.org/2000/svg" class="h-6 w-6" fill="none" viewBox="0 0 24 24" stroke="currentColor">
        <path stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="M5 13l4 4L19 7" />
    </svg>
    Save
</button>

<!-- After -->
<button>
    @heroicon('solid/arrow-up-right', class="h-6 w-6")
    Save
</button>

Implementation Patterns

Usage Patterns

Consistent Icon Sizing: Use Tailwind’s utility classes for sizing (e.g., h-4 w-4, h-6 w-6, h-8 w-8).
```
@heroicon('solid/bell', class="h-5 w-5")
```

Dynamic Icons with Blade Logic: Pass dynamic classes or icon names based on conditions:

@heroicon(
    $isActive ? 'solid/check-circle' : 'outline/x-circle',
    class="h-6 w-6 text-" . ($isActive ? 'green-500' : 'red-500')
)

Component Integration: Create reusable Blade components for common icon patterns:

@component('components.icon', [
    'name' => 'solid/arrow-left',
    'size' => 'h-6 w-6',
    'color' => 'text-gray-500',
])
@endcomponent

Dark Mode Support: Leverage Tailwind’s dark mode classes:

@heroicon('solid/moon', class="h-6 w-6 dark:text-gray-500")

Micro Interactions: Combine with Alpine.js for hover/focus effects:

<div x-data="{ hover: false }" @mouseover="hover = true" @mouseleave="hover = false">
    @heroicon(
        $hover ? 'solid/star' : 'outline/star',
        class="h-6 w-6 transition-colors duration-200"
    )
</div>

Workflows

Design System Alignment:

Define a naming convention for icons in your tailwind.config.js (e.g., prefix all custom icons with custom/).

Example:

// tailwind.config.js
theme: {
    extend: {
        fontFamily: {
            sans: ['Inter', 'sans-serif'],
        },
        // Custom icon prefixes
        icon: {
            prefix: 'custom/',
        },
    },
},

Icon Inventory Management:

Maintain a README.md or spreadsheet listing all used icons (e.g., solid/user, outline/cog).

Example:

| Icon Name       | Usage Context          | Component          |
|-----------------|-------------------------|--------------------|
| solid/check     | Success messages        | Alert Component    |
| outline/plus    | Add buttons             | Form Actions       |

Theming:

Extend Tailwind’s theme to include custom icon colors:

// tailwind.config.js
theme: {
    extend: {
        colors: {
            'icon-primary': '#3b82f6',
            'icon-secondary': '#10b981',
        },
    },
},

Usage:

@heroicon('solid/star', class="h-6 w-6 text-icon-primary")

Livewire/Inertia Integration:

Pass icon names dynamically from Laravel to Blade:

// Livewire Component
public $iconName = 'solid/check-circle';

<!-- Blade View -->
@heroicon($iconName, class="h-6 w-6")

Accessibility:

Add aria-hidden and focusable="false" for decorative icons:

@heroicon('solid/info-circle', class="h-5 w-5 text-blue-500", aria-hidden="true", focusable="false")

Use aria-label for actionable icons:

<button aria-label="Notifications">
    @heroicon('solid/bell', class="h-6 w-6")
</button>

Integration Tips

Laravel Mix/Vite: Ensure Heroicons are processed during builds. If using Vite, add this to vite.config.js:
```
optimizeDeps: {
    include: ['@heroicons/tailwind'],
},
```

PurgeCSS: If using Tailwind’s JIT mode or PurgeCSS, ensure Heroicons are not purged:

// tailwind.config.js
purge: {
    content: [
        './resources/**/*.blade.php',
        './resources/**/*.js',
        './resources/**/*.vue',
    ],
    // Add Heroicons to safelist
    safelist: [
        /^heroicon-/,
        /^h-\d+$/,
        /^w-\d+$/,
        /^text-.*$/,
    ],
},

Testing:
- Test icon rendering in all supported browsers (Chrome, Firefox, Safari, Edge).
- Validate dark mode support if enabled:
```
npm run dev -- --mode dark
```
Performance:
- For critical paths, inline the SVG directly in Blade to avoid extra HTTP requests (though this reduces maintainability).
- Use h-4 w-4 (mini variants) for non-critical icons to reduce file size.

Custom Icons:

To add custom icons, extend the Heroicons package or use Tailwind’s @apply:

<svg class="h-6 w-6 @apply fill-current text-blue-500" ...>
    <!-- Custom SVG path -->
</svg>

Gotchas and Tips

Pitfalls

Blade Cache Issues:
- If icons fail to render after installation, clear Blade cache:
```
php artisan view:clear
```
- Tip: Add this to your composer.json scripts for future updates:
```
"post-update-cmd": [
    "@php artisan view:clear"
]
```
Tailwind Version Mismatches:
- Heroicons v2 requires Tailwind CSS v3+. If using v2, expect broken styles.
- Fix: Update Tailwind or pin versions in composer.json:
```
"require": {
    "tailwindcss": "^3.0"
}
```
Missing Icons:
- Typos in icon names (e.g., solid/check-cirle instead of solid/check-circle) will render nothing.
- Debug: Check the Heroicons Explorer for correct names.
CSS Conflicts:
- Custom CSS overriding Tailwind’s fill-current or stroke-current can break icons.
- Fix: Use !important sparingly or inspect the SVG with browser dev tools.
Build Step Failures:
- If using Vite/Laravel Mix, ensure @heroicons/tailwind is included in dependencies.
- Error: Module not found: Error: Can't resolve '@heroicons/tailwind'.
- Fix: Run npm install @heroicons/tailwind and rebuild assets.
Dark Mode Quirks:
- Icons in dark mode may inherit unexpected colors if not explicitly styled.
- Tip: Use

Heroicons Laravel Package