Heroicons Laravel Package

Getting Started

Minimal Setup

1. Install the package:

   composer require wireui/heroicons
   

2. Ensure Tailwind CSS is configured (v3+ recommended). Add the WireUI plugin to tailwind.config.js:

   plugins: [
       require('wireui/tailwind'),
   ],
   

3. Publish assets (if using Laravel Mix/Vite):

   npm install @heroicons/tailwind
   npm run dev
   

First Use Case: Replacing a Manual SVG

Replace this manual SVG:

<img src="{{ asset('images/star.svg') }}" class="h-6 w-6 text-yellow-400">

With Heroicons:

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

Where to Look First

• Blade Syntax: WireUI Heroicons Docs.
• Icon List: Heroicons Official Gallery (filter by solid, outline, or mini).
• Tailwind Integration: Verify tailwind.config.js includes the WireUI plugin.

Implementation Patterns

Core Workflows

1. Icon Selection and Rendering

• Solid Icons: Use for filled states (e.g., buttons, active items).

  @heroicon('solid/check', class="h-5 w-5 text-green-500")
  

• Outline Icons: Use for inactive/hover states.

  @heroicon('outline/star', class="h-5 w-5 text-gray-400 hover:text-gray-500")
  

• Mini Icons: For compact UIs (e.g., tooltips, badges).

  @heroicon('mini/arrow-right', class="h-4 w-4")
  

2. Dynamic Icons with Blade Logic

Leverage Blade directives to conditionally render icons:

@if ($user->is_active)
    @heroicon('solid/check-circle', class="text-green-500")
@else
    @heroicon('solid/x-circle', class="text-red-500")
@endif

3. Component Integration

Embed icons in reusable Blade components (e.g., buttons, cards):

@component('components.button', [
    'icon' => 'solid/arrow-right',
    'iconClasses' => 'h-5 w-5',
    'text' => 'Submit'
])
@endcomponent

4. Dark Mode Support

Use Tailwind’s dark mode classes with icons:

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

Integration Tips

With Livewire

Pass icon props dynamically:

<x-livewire-button wire:click="submit">
    @heroicon('solid/paper-airplane', class="h-5 w-5 mr-2")
    Submit
</x-livewire-button>

With Inertia.js

Render icons in Vue/React components via Blade:

<div x-data>
    <button @click="$wire.submit">
        @heroicon('solid/upload', class="h-5 w-5 inline")
        <span>Upload</span>
    </button>
</div>

Theming Icons

Extend Tailwind’s theme to customize icon colors:

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

Usage:

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

Performance Optimization

• Tree-shaking: Configure Vite to include only used icons:

  // vite.config.js
  optimizeDeps: {
      include: ['@heroicons/tailwind'],
  },
  

• Critical Icons: Inline essential icons in HTML to reduce render-blocking.

Gotchas and Tips

Pitfalls

1. Missing Tailwind Plugin

   • Symptom: Icons render as broken SVGs or with incorrect styles.
   • Fix: Ensure wireui/tailwind is added to tailwind.config.js plugins.

2. Blade Cache Issues

   • Symptom: Icons fail to render after package installation.
   • Fix: Clear Blade cache:

     php artisan view:clear
     

3. Version Mismatches

   • Symptom: Icons appear misaligned or broken (e.g., after Tailwind update).
   • Fix: Pin versions in composer.json and package.json:

     "wireui/heroicons": "^2.10.0",
     "@heroicons/tailwind": "^2.0.11"
     

4. Build Step Failures

   • Symptom: Icons missing in production.
   • Fix: Verify Vite/Mix processes Heroicons:

     npm run build
     

   • Add to purge config if using Tailwind JIT:

     // tailwind.config.js
     purge: [
         './resources/views/**/*.blade.php',
         './resources/js/**/*.js',
         './vendor/wireui/**/*.blade.php',
     ],
     

5. Mini Icons Scaling

   • Symptom: Mini icons appear too small/large.
   • Fix: Use explicit classes (e.g., h-3.5 w-3.5) or adjust Tailwind’s fontSize scale.

Debugging

• Inspect SVG Output: Right-click an icon in the browser → "Inspect" to verify SVG markup and classes.
• Check Tailwind Output: Run npx tailwindcss -i input.css -o output.css --watch to debug CSS generation.
• Validate Blade Syntax: Use @error directives to catch syntax issues:

  @error
      <div class="bg-red-100 border border-red-400 text-red-700 px-4 py-3 rounded">
          Blade error: {{ $e->getMessage() }}
      </div>
  @enderror
  

Extension Points

1. Custom Icon Sets

   • Override default icons by publishing assets:

     php artisan vendor:publish --tag=wireui-heroicons
     

   • Modify published SVGs in resources/views/vendor/wireui/heroicons.

2. Icon Animations

   • Use Tailwind animations with icons:

     @heroicon('solid/spinner', class="h-5 w-5 animate-spin")
     

   • For complex animations, inline SVG with JavaScript:

     <svg class="animate-pulse" ...>...</svg>
     

3. Accessibility

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

     @heroicon('solid/star', class="h-5 w-5", ['aria-hidden' => 'true', 'focusable' => 'false'])
     

   • Use aria-label for interactive icons:

     <button aria-label="Submit form">
         @heroicon('solid/paper-airplane', class="h-5 w-5")
     </button>
     

4. Dark Mode Customization

   • Override dark mode colors in tailwind.config.js:

     darkMode: 'class',
     theme: {
         extend: {
             colors: {
                 'icon-dark': '#9ca3af',
             },
         },
     },
     

   • Usage:

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

Pro Tips

• Icon Naming: Use Heroicons’ official naming (e.g., solid/check-circle vs. outline/check-circle).
• Consistency: Standardize icon sizes across the app (e.g., h-5 w-5 for buttons, h-4 w-4 for tooltips).
• Search Icons: Use the Heroicons search tool to find icons by keyword.
• Laravel Mix/Vite: Ensure Heroicons are processed in your build pipeline. For Vite, add to resolve.alias:

  // vite.config.js
  resolve: {
      alias: {
          '@heroicons': path.resolve(__dirname, 'node_modules/@heroicons/tailwind'),
      },
  },