Filament Flux Laravel Package

Getting Started

Minimal Setup

1. Install the package:

   composer require jeffersongoncalves/filament-flux
   php artisan make:filament-theme admin
   php artisan filament-flux:install --panel=admin
   npm run build
   

2. Register the plugin in your Panel provider:

   public function panel(Panel $panel): Panel
   {
       return $panel->plugins([
           FilamentFluxPlugin::make(),
       ]);
   }
   

3. First use case: Replace a single form field in a Resource:

   use Jeffersongoncalves\FilamentFlux\Forms\Components\FluxInput;
   
   FluxInput::make('email')
       ->email()
       ->required();
   

Key First Steps

• Verify the filament-flux CSS is injected (check resources/css/filament/{panel}/theme.css).
• Test the Flux UI in a non-critical form first (e.g., a Settings page).
• Use useEverywhere() cautiously—start with granular replacements.

Implementation Patterns

Workflow: Progressive Adoption

1. Start with forms: Replace TextInput, Select, or Checkbox in a Resource:

   FluxInput::make('name')
       ->fluxIcon('user')
       ->fluxClearable();
   

2. Extend existing fields: Flux fields inherit Filament’s methods (e.g., ->relationship()) but add Flux-specific methods:

   FluxSelect::make('status')
       ->options(['active', 'inactive'])
       ->searchable()
       ->fluxVariant('pills'); // Flux-specific
   

3. Table columns: Replace BadgeColumn with FluxBadgeColumn:

   FluxBadgeColumn::make('status')
       ->fluxColor(['active' => 'lime', 'inactive' => 'zinc'])
       ->fluxIcon('check-circle');
   

4. Navigation: Opt into Flux navigation incrementally:

   FilamentFluxPlugin::make()->useFluxNavigation([
       'sidebar' => true,
       'topbar' => false,
   ]);
   

Integration Tips

• Mixed environments: Use useEverywhere() with opt-outs for specific fields:

  FilamentFluxPlugin::make()->useEverywhere([
      'select' => false, // Keep Filament’s select for legacy integrations
  ]);
  

• Custom Blade components: Override Filament views in resources/views/filament/ to extend Flux components (e.g., flux::dropdown).
• Theme sync: Leverage the built-in theme switcher bridge—no manual CSS toggles needed.

Common Patterns

Gotchas and Tips

Pitfalls

1. CSS Conflicts:

   • Flux uses Tailwind’s zinc scale (not Filament’s gray). Replace gray-* with zinc-* in custom CSS.
   • Fix: Override theme.css or use fluxColor() methods to map Filament colors to Flux.

2. Missing Features:

   • Flux lacks Filament’s pageOptions dropdown in pagination. Disable the pagination component if needed:

     FilamentFluxPlugin::make()->useFluxComponents(['pagination' => false]);
     

   • Workaround: Use Filament’s native pagination in tables where pagination controls are critical.

3. Icon System:

   • Flux icons require explicit fluxIcon() calls. Filament’s icon() method won’t work.
   • Tip: Use HeroiconNormalizer for mixed icon sets (e.g., fluxIcon('heroicon-o-user')).

4. Modal Limitations:

   • Flux’s free tier lacks <flux:modal>. Use Filament’s native modals for actions:

     FluxAction::make('delete')
         ->requiresConfirmation()
         ->action(...);
     

5. Performance:

   • Flux components add ~50KB to your bundle. Test in production to monitor load times.
   • Optimization: Disable unused components (e.g., useFluxComponents(['badge' => false])).

Debugging

• Console Errors: Check for flux.appearance or flux.toast warnings. Ensure @fluxScripts is injected:

  FilamentFluxPlugin::make()->injectScripts(true);
  

• View Overrides: If a Flux component renders incorrectly, verify your resources/views/filament/ overrides exist. Fallback to vendor views:

  php artisan vendor:publish --tag=filament-flux-views
  

Extension Points

1. Custom Flux Components: Extend Jeffersongoncalves\FilamentFlux\Forms\Components\FluxField to create domain-specific fields:

   class CustomFluxField extends FluxField {
       protected static string $view = 'filament-flux::forms.custom-field';
   }
   

2. Theme Customization: Override Flux’s default theme variables in resources/css/filament-flux.css:

   @layer flux-components {
       .flux-input {
           --flux-input-border-color: #e5e7eb;
       }
   }
   

3. Livewire Events: Dispatch Flux-specific events for custom interactions:

   $this->dispatch('flux-toast', toast: [
       'title' => 'Success',
       'message' => 'Action completed',
   ]);
   

   Render in your layout:

   <x-flux::toast.group />
   

Pro Tips

• Dark Mode: Flux’s dark mode syncs automatically with Filament’s theme switcher. No extra config needed.
• Accessibility: Flux components include ARIA attributes by default. Add ->fluxLabel() for custom labels:

  FluxInput::make('name')->fluxLabel('Full Name');
  

• Localization: Flux supports x-flux-locale directives. Use app()->setLocale() in your Panel provider:

  app()->setLocale('es');