Getting Started

Minimal Setup

Install the package and a blade-icons pack (Heroicons recommended):

composer require nickperkins/blade-icon-picker blade-ui-kit/blade-heroicons

Publish assets:

php artisan vendor:publish --tag=icon-picker-assets

Include in your layout (place JS after Alpine.js):

<head>
    <link rel="stylesheet" href="{{ asset('vendor/icon-picker/icon-picker.css') }}">
</head>
<body>
    <!-- ... -->
    <script src="{{ asset('vendor/icon-picker/icon-picker.js') }}"></script>
</body>

First Use Case

Add the component to a Livewire form:

<x-icon-picker::icon-picker wire:model="menuIcon" :value="$menuIcon" />

Required props: wire:model (Livewire binding) + :value (initial value)
Default behavior: Searchable grid, lazy rendering, keyboard navigation

Implementation Patterns

Core Workflow

Livewire Property Binding

// Livewire component
public string $icon = ''; // Default empty string

<x-icon-picker::icon-picker wire:model="icon" :value="$icon" />

Form Integration

<form wire:submit="save">
    <x-icon-picker::icon-picker wire:model="icon" />
    @error('icon') <p class="text-red-500">{{ $message }}</p> @enderror
    <button type="submit">Save</button>
</form>

Validation

public function rules(): array {
    return ['icon' => ['required', 'string']];
}

Advanced Patterns

Conditional Rendering

@if($showIconPicker)
    <x-icon-picker::icon-picker wire:model="icon" />
@endif

Dynamic Placeholder

<x-icon-picker::icon-picker
    wire:model="icon"
    placeholder="{{ __('Select a ' . $context . ' icon') }}"
/>

Disabled State

<x-icon-picker::icon-picker
    wire:model="icon"
    disabled="{{ $isReadonly }}"
/>

Integration Tips

Icon Packs: Works with any blade-ui-kit/blade-* pack (Heroicons, FontAwesome). Install additional packs as needed.
Dark Mode: Use ip-dark class or data-theme="dark" on parent elements.

Theming: Override CSS variables:

.icon-picker-root {
    --ip-primary: #3b82f6; /* Tailwind blue-500 */
}

Livewire 3: Auto-registers with Alpine—no manual Alpine.data() required.

Gotchas and Tips

Common Pitfalls

Missing value Prop
- Error: Component won't initialize properly.
- Fix: Always pass :value="$icon" alongside wire:model.
No Icon Packs Installed
- Error: Shows "No icon sets found" message.
- Fix: Install blade-ui-kit/blade-heroicons or another compatible pack.
JS/CSS Not Loaded
- Error: Component appears broken or non-functional.
- Fix: Ensure assets are published and loaded in the correct order (CSS before JS, JS after Alpine).
Livewire 2 Compatibility
- Error: JS fails to auto-register.
- Fix: Manually initialize with Alpine.data('iconPicker', {}) if using Livewire 2.

Debugging Tips

Check Console: Look for Alpine.js errors (e.g., missing x-data or x-model).
Inspect Network: Verify icon list payload is loaded (should be ~8KB gzipped).
Search Behavior: Substring matching is case-insensitive. Type ar le to find heroicon-o-arrow-left.

Extension Points

Custom Icon Sets
- Register additional blade-icons packs via the service provider:
```
BladeIcons::register();
```

Override Defaults

Publish the config (if added in future versions) or extend the CSS:

.icon-picker-grid {
    grid-template-columns: repeat(8, 1fr); /* Custom columns */
}

Inline Mode
- To always show the dropdown, modify the JS to remove the toggle logic (advanced).
Performance
- For large icon sets (>1,000 icons), consider pre-filtering packs or implementing server-side pagination (future feature).

Pro Tips

Accessibility: The component supports keyboard navigation (arrow keys, Enter, Escape) out of the box.
Validation: Use @error directives for Livewire validation messages.

Dark Mode: Mirror OS preference with:

@media (prefers-color-scheme: dark) {
    .icon-picker-root { --ip-bg: #1f2937; }
}

Testing: Use livewire() with ->call('save') to test form submissions.

Blade Icon Picker Laravel Package