Filament Shadcn Theme Laravel Package

Getting Started

Minimal Setup

1. Install the package:

   composer require openplain/filament-shadcn-theme
   

2. Publish the config (if customization is needed):

   php artisan vendor:publish --provider="Openplain\FilamentShadcnTheme\FilamentShadcnThemeServiceProvider" --tag="config"
   

3. Apply the theme in app/Providers/AppServiceProvider.php:

   use Openplain\FilamentShadcnTheme\Facades\FilamentShadcnTheme;
   
   public function boot(): void
   {
       FilamentShadcnTheme::apply();
   }
   

4. Verify by toggling dark mode in Filament (buttons/inputs should invert colors automatically).

First Use Case: Quick Aesthetic Overhaul

Replace Filament’s default theme with Shadcn’s Default theme (light/dark-aware) in 5 minutes:

// config/filament.php
'panel' => [
    'theme' => Openplain\FilamentShadcnTheme\FilamentShadcnTheme::class,
],

No additional CSS or JS required—colors adapt dynamically.

Implementation Patterns

1. Theme Customization

Override default colors via config (config/filament-shadcn-theme.php):

'colors' => [
    'primary' => [
        'light' => '#1e293b',  // Dark charcoal (light mode)
        'dark'  => '#f8fafc',  // Light gray (dark mode)
    ],
    'danger' => [
        'light' => '#dc2626',
        'dark'  => '#fecaca',
    ],
],

Pro Tip: Use Shadcn’s color palette for consistency.

2. Selective Theme Application

Apply the theme only to specific panels (e.g., admin vs. public dashboard):

// In a Filament Panel provider
public function panel(Panel $panel): Panel
{
    return $panel
        ->theme(FilamentShadcnTheme::class)
        ->id('admin');
}

3. Extending with Shadcn Components

Leverage Shadcn’s UI system for custom Filament widgets:

use Openplain\FilamentShadcnTheme\Components\ShadcnButton;

ShadcnButton::make('Submit')
    ->action(fn () => /* ... */)
    ->color('primary'),

Note: The package includes pre-built Shadcn-compatible components (e.g., ShadcnCard, ShadcnInput).

4. Dark Mode Sync with System Preference

Automatically sync Filament’s dark mode with the user’s OS preference:

// app/Providers/AppServiceProvider.php
use Openplain\FilamentShadcnTheme\Facades\FilamentShadcnTheme;

public function boot(): void
{
    FilamentShadcnTheme::apply();
    FilamentShadcnTheme::enableSystemDarkMode();
}

5. Integration with Filament Forms/Tables

Ensure form inputs and table cells respect the theme:

use Openplain\FilamentShadcnTheme\Components\ShadcnTextInput;

TextInput::make('name')
    ->columnSpanFull()
    ->extraAttributes(['class' => 'shadcn-input']),  // Uses Shadcn styles

Gotchas and Tips

Pitfalls

1. Caching Issues:

   • Clear Filament’s view cache after installing:

     php artisan filament:cache:clear
     

   • Symptom: Theme colors not updating despite config changes.

2. Conflicting CSS:

   • If using custom Filament CSS, ensure no hardcoded colors (e.g., background-color: #3b82f6) override the theme.
   • Fix: Use --filament-primary-500 CSS variables instead.

3. Dark Mode Detection Lag:

   • System dark mode changes may not trigger immediately in Filament.
   • Workaround: Add a manual toggle button:

     use Openplain\FilamentShadcnTheme\Facades\FilamentShadcnTheme;
     
     Button::make('Toggle Dark Mode')
         ->action(fn () => FilamentShadcnTheme::toggleDarkMode()),
     

Debugging

• Inspect Colors: Use browser dev tools to check if --filament-primary-* variables are applied.
• Log Theme Events:

  FilamentShadcnTheme::on('theme-applied', fn () => Log::info('Theme applied!'));
  

Extension Points

1. Add Custom Themes: Create a new theme class by extending FilamentShadcnTheme:

   class CustomShadcnTheme extends FilamentShadcnTheme
   {
       protected function getColors(): array
       {
           return [
               'primary' => ['light' => '#3b82f6', 'dark' => '#60a5fa'],
           ];
       }
   }
   

   Register it in config/filament-shadcn-theme.php:

   'themes' => [
       'custom' => CustomShadcnTheme::class,
   ],
   

2. Override Component Styles: Publish the package’s assets and modify:

   php artisan vendor:publish --provider="Openplain\FilamentShadcnTheme\FilamentShadcnThemeServiceProvider" --tag="assets"
   

   Edit resources/css/filament-shadcn-theme.css.

3. Localization: The package supports RTL (right-to-left) layouts. Ensure your Filament config includes:

   'direction' => 'rtl',
   

Pro Tips

• Performance: The package uses CSS variables for dynamic theming—no runtime JS overhead.
• Accessibility: Colors are pre-validated for WCAG contrast ratios (tested in light/dark modes).
• Shadcn Ecosystem: Pair with shadcn-ui/laravel for consistent styling across your app.