Flowbite Blade Icons Laravel Package

Getting Started

Minimal Steps

1. Install the package:

   composer require themesberg/flowbite-blade-icons
   

2. Use an icon in a Blade view:

   <x-fwb-o-adjustments-horizontal class="w-6 h-6 text-gray-500" />
   

   • Replace fwb-o-adjustments-horizontal with any Flowbite icon.
   • For solid icons, use fwb-s-* prefix (e.g., <x-fwb-s-adjustments-horizontal />).

3. Verify the icon renders in your view. No additional configuration is required for basic usage.

First Use Case: Adding Icons to a Navigation Bar

<nav class="flex space-x-4">
    <x-fwb-o-home class="w-5 h-5" />
    <x-fwb-o-settings class="w-5 h-5" />
    <x-fwb-o-user class="w-5 h-5" />
</nav>

Result: A navigation bar with three icons, styled via Tailwind classes.

Implementation Patterns

1. Component-Based Usage (Recommended)

Use Blade components for type-safe, IDE-friendly icon references:

<!-- Outline icon -->
<x-fwb-o-cart class="text-red-500 hover:text-red-700" />

<!-- Solid icon -->
<x-fwb-s-star class="text-yellow-400" />

<!-- With dynamic classes -->
<x-fwb-o-bell class="{{ request()->has('notifications') ? 'text-blue-500 pulse' : 'text-gray-400' }}" />

Pattern: Icon Sets in a Single View

Group related icons (e.g., a dashboard toolbar):

<div class="flex space-x-2">
    @foreach(['home', 'settings', 'notifications', 'user'] as $icon)
        <x-fwb-o-{{ $icon }} class="w-5 h-5 text-gray-600 hover:text-gray-900" />
    @endforeach
</div>

2. Directives for Dynamic Icons

Use the @svg directive when icons are determined at runtime:

@svg(
    $name = $user->role === 'admin' ? 'fwb-s-shield-check' : 'fwb-o-user',
    $classes = 'w-6 h-6',
    $attributes = ['aria-label' => $user->role]
)

Pattern: Dynamic Icons with Fallbacks

@svg(
    $name = config('app.icon.' . $feature->type) ?? 'fwb-o-question-mark',
    $classes = 'w-5 h-5 text-gray-500'
)

3. Configuration for Global Defaults

Publish the config to set default classes/attributes for all icons:

php artisan vendor:publish --tag=flowbite-blade-icons-config

Edit config/flowbite-blade-icons.php:

'default_classes' => 'w-5 h-5 text-gray-500',
'default_attributes' => ['aria-hidden' => 'true'],

Result: All icons inherit these defaults unless overridden:

<x-fwb-o-home /> <!-- Uses w-5 h-5 text-gray-500 aria-hidden="true" -->
<x-fwb-o-settings class="text-blue-500" /> <!-- Overrides text color -->

4. Raw SVG Assets (Advanced)

Publish SVG files for use in non-Blade contexts (e.g., JavaScript, CSS):

php artisan vendor:publish --tag=flowbite-blade-icons --force

Use in views:

<img src="{{ asset('vendor/flowbite-blade-icons/o-adjustments-horizontal.svg') }}" alt="Settings" width="20" height="20" />

Pattern: SVG Sprites

Combine SVGs into a sprite sheet for reduced HTTP requests:

# Use a tool like `svgsprite` to process published SVGs
svgsprite --input resources/svg --output public/sprite.svg

Reference in HTML:

<svg class="w-6 h-6">
    <use href="{{ asset('sprite.svg#o-adjustments-horizontal') }}" />
</svg>

5. Integration with Flowbite Components

Pair icons with Flowbite’s UI components (e.g., buttons, dropdowns):

<button class="flex items-center gap-2 px-4 py-2 bg-blue-600 text-white rounded">
    <x-fwb-o-settings class="w-5 h-5" />
    Settings
</button>

Pattern: Icon + Text Buttons

<x-dropdown>
    <x-slot name="trigger">
        <button class="flex items-center gap-1">
            <x-fwb-o-cog />
            <span>Configure</span>
        </button>
    </x-slot>
    <!-- Dropdown items -->
</x-dropdown>

6. Caching for Performance

Enable Blade Icons caching to reduce view compilation time:

php artisan cache:clear

Configure in config/blade-icons.php (published by blade-ui-kit/blade-icons):

'cache' => [
    'enabled' => true,
    'path' => storage_path('framework/cache/blade-icons'),
],

Gotchas and Tips

Pitfalls

1. Icon Naming Confusion

   • Gotcha: Mixing fwb-o-* (outline) and fwb-s-* (solid) prefixes.
   • Fix: Use autocomplete in your IDE (e.g., VSCode + Laravel Blade snippets) to avoid typos.
   • Tip: Bookmark the Flowbite Icons preview for quick reference.

2. Caching Issues

   • Gotcha: After updating the package, cached Blade views may still use old icons.
   • Fix: Clear Blade cache:

     php artisan view:clear
     php artisan cache:clear
     

   • Tip: Disable caching during development ('cache' => ['enabled' => false] in blade-icons.php).

3. SVG currentColor Quirks

   • Gotcha: Icons may not inherit colors if fill="currentColor" is missing (pre-v1.2.1).
   • Fix: Update the package:

     composer update themesberg/flowbite-blade-icons
     

   • Tip: Test with style="color: red" to verify inheritance:

     <x-fwb-o-home style="color: red" />
     

4. Config Publishing Overwrite

   • Gotcha: Running vendor:publish multiple times overwrites config/flowbite-blade-icons.php.
   • Fix: Merge changes manually or use --force carefully.

5. IDE Autocomplete Limitations

   • Gotcha: Some IDEs (e.g., PHPStorm) don’t auto-suggest Blade components by default.
   • Fix: Add this to .editorconfig:

     [*.blade.php]
     blade_component_autocomplete = true
     

Debugging Tips

1. Inspect Rendered SVG Use browser dev tools to verify the compiled SVG:

   <x-fwb-o-home class="w-6 h-6" style="outline: 1px solid red" />
   

   • Check if classes/attributes are applied correctly.

2. Check for Typos

   • Error: Component class [fwb-o-home] does not exist.
   • Solution: Verify the icon name matches Flowbite’s list.

3. Disable Caching Temporarily Set 'cache' => ['enabled' => false] in blade-icons.php to test changes without clearing cache.

4. Validate SVG Output Ensure SVGs render correctly in isolation:

   @svg('fwb-o-home', 'w-0 h-0', ['style' => 'display: none'])
   

   • If this fails, the package installation may be corrupted. Reinstall:

     composer remove themesberg/flowbite-blade-icons && composer require themesberg/flowbite-blade-icons
     

Extension Points

1. Custom Icon Sets

   • How: Extend the package by publishing and modifying the SVG directory (resources/svg).
   • Steps:
     1. Publish SVGs:

        php artisan vendor:publish --tag=flowbite-blade-icons --force
        

     2. Add custom SVGs to resources/svg/custom/.
     3. Register them in a service provider:

        BladeIcons::register('fwb-c-*', resource_path('svg/custom'));
        

2. Dynamic Icon Resolution

   • Use Case: Load icons from a database or API.