Getting Started

Minimal Steps

Installation:
```
composer require wireui/heroicons
```
No additional configuration is required—Blade components auto-register.
First Usage: Insert an icon in a Blade view:
```
<x-heroicon-o-home class="h-6 w-6 text-blue-500" />
```
- o- = outline (alternatives: s- for solid, m- for mini, l- for micro).
- Replace home with any Heroicons name.
Verify: Check the WireUI Heroicons docs for the full icon list and variants.

First Use Case: Admin Dashboard Navigation

Replace static SVGs in a Laravel admin panel with dynamic Blade components:

<nav class="flex space-x-4 p-4 bg-gray-100">
    <a href="{{ route('dashboard') }}" class="flex items-center">
        <x-heroicon-o-home class="h-6 w-6 text-indigo-600" />
        <span>Dashboard</span>
    </a>
    <a href="{{ route('users.index') }}" class="flex items-center">
        <x-heroicon-o-users class="h-6 w-6 text-indigo-600" />
        <span>Users</span>
    </a>
    <a href="{{ route('settings') }}" class="flex items-center">
        <x-heroicon-o-cog class="h-6 w-6 text-indigo-600" />
        <span>Settings</span>
    </a>
</nav>

Key Benefits:

Consistent sizing/color via Tailwind classes.
No manual SVG management or CDN dependencies.
Automatic updates when Heroicons releases new versions.

Implementation Patterns

Core Workflows

1. Static Icons in Blade Views

Use Heroicons in buttons, cards, or tooltips:

<!-- Button with icon -->
<button class="px-4 py-2 bg-blue-500 text-white rounded hover:bg-blue-600">
    <x-heroicon-o-paper-airplane class="h-5 w-5 inline mr-2" />
    Submit
</button>

<!-- Card header -->
<div class="p-4 border rounded-lg">
    <div class="flex items-center mb-2">
        <x-heroicon-o-shopping-cart class="h-6 w-6 text-green-500 mr-2" />
        <h3 class="text-lg font-medium">Orders</h3>
    </div>
    <p class="text-gray-600">12 new orders today</p>
</div>

Tailwind Integration: Use h-* w-* for sizing and text-* for colors.

Accessibility: Add aria-hidden="true" if the icon is decorative:

<x-heroicon-o-check-circle aria-hidden="true" class="h-5 w-5 text-green-500" />

2. Dynamic Icons with Livewire

Bind icon visibility/state to Livewire components:

<!-- Livewire component -->
<div class="flex space-x-2">
    <x-heroicon-o-check-circle
        class="h-5 w-5 text-green-500"
        x-show="isSuccess"
    />
    <x-heroicon-o-x-circle
        class="h-5 w-5 text-red-500"
        x-show="!isSuccess"
    />
</div>

Livewire Controller:

public $isSuccess = false;

public function markAsSuccess() {
    $this->isSuccess = true;
}

3. Icon Variants and Sizes

Leverage Heroicons' multiple styles and sizes:

<!-- Outline (default) -->
<x-heroicon-o-home class="h-6 w-6" />

<!-- Solid -->
<x-heroicon-s-home class="h-6 w-6" />

<!-- Mini -->
<x-heroicon-m-home class="h-5 w-5" />

<!-- Micro -->
<x-heroicon-l-home class="h-4 w-4" />

<!-- Custom size -->
<x-heroicon-o-home class="h-10 w-10" />

4. Dark Mode Support

Use Tailwind’s dark: variant for automatic theme switching:

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

Integration Tips

With Tailwind CSS

Safelist Heroicons Classes: Add to tailwind.config.js to prevent purging:

module.exports = {
    safelist: [
        /^h-\d+$/,
        /^w-\d+$/,
        /^text-.*$/,
        /^heroicon-.*/,
    ],
}

Custom Icon Colors: Define reusable color classes in your Tailwind config:

module.exports = {
    theme: {
        extend: {
            colors: {
                'icon-primary': '#3b82f6',
                'icon-secondary': '#10b981',
            },
        },
    },
}

Usage:

<x-heroicon-o-home class="h-6 w-6 text-icon-primary" />

With Livewire

Dynamic Icon Switching: Pass icon names or styles via Livewire props:

public $iconName = 'home';
public $iconStyle = 'o'; // 'o' for outline, 's' for solid

<x-heroicon-{{ $iconStyle }}-{{ $iconName }} class="h-6 w-6" />

Conditional Icons:

@if($user->isActive)
    <x-heroicon-o-check-circle class="h-5 w-5 text-green-500" />
@else
    <x-heroicon-o-x-circle class="h-5 w-5 text-red-500" />
@endif

With Alpine.js

Interactive Icons: Toggle icons dynamically with Alpine.js:

<div x-data="{ isActive: false }">
    <button @click="isActive = !isActive">
        <x-heroicon-o-check-circle
            x-show="!isActive"
            class="h-5 w-5 text-green-500"
        />
        <x-heroicon-o-x-circle
            x-show="isActive"
            class="h-5 w-5 text-red-500"
        />
    </button>
</div>

With Inertia.js

Pass Icons as Strings: Return Blade components as strings in Inertia responses:

return Inertia::render('Dashboard', [
    'icon' => "<x-heroicon-o-home class='h-6 w-6' />",
]);

Parse the HTML in your Vue/React component:

<template>
    <div v-html="icon"></div>
</template>

With Blade Components

Reusable Icon Components: Create a custom Blade component for consistent icon usage:

<!-- resources/views/components/icon.blade.php -->
<x-heroicon-{{ $style }}-{{ $name }} class="h-{{ $size }} w-{{ $size }} {{ $classes }}" />