Flux Icons Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require --dev ympact/flux-icons
   npm install --save-dev @ympact/flux-icons
   

   Run the publisher to generate config and assets:

   php artisan vendor:publish --provider="Ympact\FluxIcons\FluxIconsServiceProvider" --tag="flux-icons-config"
   php artisan flux-icons:build
   

2. First Use Case Add the component to your Flux layout (e.g., resources/views/layouts/app.blade.php):

   <x-flux::icon name="bootstrap:home" />
   

   Verify the icon appears in your Livewire Flux admin panel.

Implementation Patterns

Icon Integration Workflow

1. Selecting Icons Use the name attribute with vendor prefixes (e.g., bootstrap:home, codicons:git-commit, flags:us). Reference the README table for available vendors.

2. Dynamic Icon Usage Pass dynamic names via Livewire properties:

   public $icon = 'flowbite:users';
   

   <x-flux::icon :name="$icon" />
   

3. Customizing Icon Sizes Use Tailwind classes or inline styles:

   <x-flux::icon name="mat:settings" class="w-6 h-6" />
   

4. Theming Icons Override default colors via CSS or inline styles:

   <x-flux::icon name="fluent:heart" style="color: #ef4444" />
   

Advanced Patterns

• Icon Sets for Menus Group related icons in a config file (config/flux-icons.php) for reuse:

  'sets' => [
      'admin' => ['bootstrap:gear', 'bootstrap:people', 'bootstrap:file-earmark-text'],
  ],
  

  Access via:

  <x-flux::icon name="admin.gear" />
  

• Custom SVG Handling Extend the package by adding new vendors in app/Providers/FluxIconsServiceProvider.php:

  public function boot()
  {
      $this->app->make('ympact.flux-icons')->addVendor('custom', __DIR__.'/path-to-icons');
  }
  

Gotchas and Tips

Common Pitfalls

1. Development vs. Production

   • Install as --dev dependency. Exclude built assets from production:

     npm run build -- --only=flux-icons
     

   • Ensure node_modules are not committed to version control.

2. Icon Resolution Issues

   • Flags use a fixed 4:3 aspect ratio by default. Adjust in config/flux-icons.php:

     'flags' => [
         'aspect_ratio' => '16:9', // or 'rectangle'
     ],
     

   • Rebuild assets after changes:

     php artisan flux-icons:build
     

3. Stroke Width Limitations Vendors like bootstrap, codicons, and fluent have fixed stroke widths. Use solid variants (e.g., bootstrap:house-fill) or override with CSS:

   .flux-icon-bootstrap-house-fill {
       stroke-width: 2;
   }
   

4. Caching Clear cached views and config after updates:

   php artisan view:clear
   php artisan config:clear
   

Debugging Tips

• Missing Icons Check the build logs for errors:

  php artisan flux-icons:build --verbose
  

  Ensure the vendor namespace exists in the config.

• Path Issues Verify icon paths in config/flux-icons.php point to valid directories.

Extension Points

1. Custom Vendors Add new vendors by extending the Vendor class or publishing custom assets:

   php artisan vendor:publish --tag="flux-icons-assets"
   

2. Icon Modifiers Use Alpine.js or JavaScript to toggle icon states dynamically:

   <x-flux::icon
       name="mat:favorite"
       x-data="{ filled: false }"
       @click="filled = !filled"
       :class="{ 'text-red-500': filled }"
   />
   

3. Performance Lazy-load icons in non-critical sections using loading="lazy":

   <x-flux::icon name="flowbite:clock" loading="lazy" />