Filament Better Options Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require tonegabes/filament-better-options
   

   Publish the config (if needed):

   php artisan vendor:publish --provider="ToneGabes\FilamentBetterOptions\FilamentBetterOptionsServiceProvider"
   

2. First Use Case: Replace a basic Filament Checkbox or Radio field with the enhanced version in a resource form:

   use ToneGabes\FilamentBetterOptions\Forms\Components\CheckboxList;
   
   CheckboxList::make('status')
       ->options([
           'active' => 'Active',
           'inactive' => 'Inactive',
           'pending' => 'Pending',
       ])
       ->columns(2) // For list layout
       // ->layout('CheckboxCards') // For card layout
   

3. Where to Look First:

   • Documentation: Check the GitHub README for component-specific examples.
   • Config: Review config/filament-better-options.php for global defaults (e.g., theme, debounce time).
   • Blade Templates: Inspect resources/views/vendor/filament-better-options/ for customization hooks.

Implementation Patterns

Core Workflows

1. Replacing Default Filament Fields:

   • Swap Checkbox/Radio with CheckboxList/RadioList for list layouts or CheckboxCards/RadioCards for card-based UIs.
   • Example:

     RadioList::make('priority')
         ->options([
             'low' => ['icon' => 'heroicon-o-minus', 'label' => 'Low'],
             'medium' => ['icon' => 'heroicon-o-archive', 'label' => 'Medium'],
             'high' => ['icon' => 'heroicon-o-exclamation', 'label' => 'High'],
         ])
         ->layout('RadioCards')
         ->theme('modern');
     

2. Dynamic Options:

   • Fetch options from a database or API:

     CheckboxList::make('tags')
         ->options(Tag::all()->pluck('name', 'id'))
         ->searchable()
         ->searchDebounce(300);
     

3. Bulk Operations:

   • Enable bulk select/deselect for checkboxes:

     CheckboxList::make('permissions')
         ->options(Permission::all()->pluck('name', 'id'))
         ->bulkActions()
         ->bulkActionLabel('Select All');
     

4. Theming and Styling:

   • Apply themes globally in config or per-component:

     RadioCards::make('theme_example')
         ->theme('classic')
         ->iconPosition('after');
     

5. Integration with Filament Forms:

   • Use in resource forms, pages, or widgets:

     public static function form(Form $form): Form
     {
         return $form
             ->schema([
                 CheckboxCards::make('features')
                     ->options([
                         'notifications' => 'Email Notifications',
                         'analytics' => 'Analytics Dashboard',
                     ]),
             ]);
     }
     

Advanced Patterns

• Custom Icons: Use Filament’s icon system (e.g., heroicon-o-star, tabler-star) or register custom icons via the config.
• Conditional Rendering: Combine with Filament’s visible()/hidden() methods:

  CheckboxList::make('advanced_settings')
      ->options([...])
      ->visible(fn ($record) => $record->is_admin);
  

• Validation: Leverage Filament’s built-in validation (e.g., required(), minItems()) alongside component-specific features.

Gotchas and Tips

Pitfalls

1. Performance with Large Datasets:

   • Issue: Search functionality may lag with >1000 options.
   • Fix: Use searchDebounce(500) or paginate options server-side (e.g., via ->options(fn () => Option::query()->paginate(50))).

2. Theme Conflicts:

   • Issue: Custom Tailwind classes may override themes.
   • Fix: Use !important sparingly; prefer theme-specific classes (e.g., bg-blue-500 in modern theme).

3. Icon Alias Mismatches:

   • Issue: Icons fail to load if the alias doesn’t match Filament’s registered icons.
   • Fix: Verify aliases in filament.php config or use full icon paths (e.g., tabler-icons:star).

4. Bulk Actions Edge Cases:

   • Issue: Bulk select/deselect may not persist if the form is reset.
   • Fix: Use ->persistBulkState() or handle state in the form’s dehydrateState() method.

5. Dark Mode Quirks:

   • Issue: Themes may not adapt fully to dark mode.
   • Fix: Extend the dark: variant in your Tailwind config or override component styles.

Debugging Tips

• Inspect Rendered HTML: Use browser dev tools to verify component structure (e.g., check if icons or search inputs are rendered).
• Check Console Logs: Enable debug mode (APP_DEBUG=true) to catch JavaScript errors (e.g., debounce failures).
• Clear Caches: Run php artisan view:clear if styles/icons fail to load after updates.

Extension Points

1. Custom Components: Extend the base classes (e.g., CheckboxList) to add features like:

   namespace App\Filament\Components;
   
   use ToneGabes\FilamentBetterOptions\Forms\Components\CheckboxList;
   
   class CustomCheckboxList extends CheckboxList
   {
       protected string $view = 'filament-better-options::custom-checkbox-list';
   }
   

2. Override Views: Publish and modify views:

   php artisan vendor:publish --tag="filament-better-options-views"
   

   Then edit resources/views/vendor/filament-better-options/checkbox-list.blade.php.

3. Add Global JavaScript: Register scripts in bootstrap.js:

   import { initBetterOptions } from 'filament-better-options';
   
   initBetterOptions();
   

4. Config Overrides: Customize defaults in config/filament-better-options.php:

   'default_theme' => 'minimal',
   'search_debounce' => 400,
   'bulk_actions' => [
       'label' => 'Select/Deselect All',
       'icon' => 'heroicon-o-check',
   ],
   

Pro Tips

• Combine with Filament Actions: Use component selections to trigger actions:

  CheckboxList::make('roles')
      ->options([...])
      ->afterStateUpdated(fn (Form $form) => $form->dispatchBrowserEvent('roles-updated'));
  

• Accessibility: Add aria-label or aria-describedby for screen readers:

  ->extraAttributes(['aria-label' => 'Select user permissions']);
  

• Localization: Use Filament’s translation system for option labels:

  ->options([
      'draft' => __('filament-better-options::status.draft'),
  ]);