Getting Started

Minimal Setup

Installation

composer require andreia/filament-ui-switcher

Publish the config file:

php artisan vendor:publish --provider="Andreia\FilamentUISwitcher\FilamentUISwitcherServiceProvider" --tag="config"

Register the Plugin Add to app/Providers/Filament/AdminPanelProvider.php. Since v1.1.2 the plugin exposes fluent methods, so most configuration now lives here rather than in the config file:

public function panel(Panel $panel): Panel
{
    return $panel
        ->plugins([
            \Andreia\FilamentUISwitcher\FilamentUISwitcherPlugin::make()
                ->primaryColors(['#3b82f6', '#10b981'])
                ->fontFamilies(['Inter', 'Figtree'])
                ->disableModeSwitcher(),
        ]);
}

First Use Case Access the UI switcher via the ⚙️ icon in the Filament topbar. Toggle an option and refresh the page to confirm persistence (session storage is the default out of the box).

Where to Look First

FilamentUISwitcherPlugin — the fluent builder added in v1.1.2. Confirm the exact method names with php artisan ide-helper:model output or by reading the class; they map 1:1 onto the config/filament-ui-switcher.php keys.
config/filament-ui-switcher.php — still the source of defaults and the place for anything not yet exposed fluently.
resources/views/ in the package — publish these if the topbar trigger or modal needs restyling.

Implementation Patterns

Core Workflows

Fluent Section Configuration (v1.1.2+) Prefer the fluent API for per-panel configuration. Disable sections you don't want users touching rather than hiding them with CSS:
```
FilamentUISwitcherPlugin::make()
    ->disableModeSwitcher()
    ->disableFontSizeSwitcher()
    ->primaryColors(['#3b82f6', '#10b981', '#8b5cf6']);
```
This keeps the modal tidy and avoids users setting values your theme doesn't support.
Local Fonts (v1.1.2+) The plugin now supports fonts served from your own application instead of remote font providers. Workflow:
1. Drop the font files into a public path (or your Vite resources/fonts + build output).
2. Declare @font-face rules in your panel CSS so the browser can resolve the family name.
3. Register the family name via the fluent method or config:
```
FilamentUISwitcherPlugin::make()->fontFamilies(['Inter', 'Acme Local']);
```
Useful for GDPR-sensitive deployments, air-gapped servers, or brand fonts that aren't on Google Fonts.
Customizing UI Globally Modify config/filament-ui-switcher.php for defaults that apply to every panel: primary_colors, font_families, font sizes, and feature toggles like mode_switcher_enabled.

Database Storage Integration Add the trait to your User model and switch storage:

use Andreia\FilamentUISwitcher\Traits\HasUISwitcherPreferences;

class User extends Authenticatable
{
    use HasUISwitcherPreferences;
}

'storage' => 'database',

Dynamic Layout Switching Apply settings programmatically via the facade:

use Andreia\FilamentUISwitcher\Facades\FilamentUISwitcher;

FilamentUISwitcher::setPrimaryColor('#3b82f6');
FilamentUISwitcher::setFontFamily('Inter');

Conditional Plugin Rendering

->plugins([
    FilamentUISwitcherPlugin::make()->visible(fn () => auth()->user()->isAdmin()),
])

Gotchas and Tips

Pitfalls

Fluent vs. Config Precedence Fluent calls in the panel provider win over config/filament-ui-switcher.php. If a user reports "my config change does nothing," check the AdminPanelProvider first — the setting is likely being overridden there (or the config cache is stale, see below).
Caching Conflicts Clear Filament and view caches after changing config:
```
php artisan filament:cache:clear
php artisan view:clear
php artisan config:clear
```
Fluent changes require a full page reload of the panel, not just a Livewire refresh.
Local Fonts Not Rendering
- The family name registered with the plugin must match the font-family in your @font-face rule exactly, including casing and spaces.
- Font files must be reachable over HTTP — a font sitting in storage/ won't resolve. Put them in public/ or ship them through Vite.
- Check the Network tab for 404s on the .woff2 file before blaming the plugin; browsers fail silently and fall back.
- Add the font file extensions to your web server's MIME map if .woff2 is served as application/octet-stream.
Database Storage Quirks
- Ensure the ui_preferences table exists (migration runs automatically).
- If using database storage, verify the user_id column matches your users table.
Livewire Version Mismatch The plugin requires Livewire 3.x or 4.x:
```
composer require livewire/livewire:^3.0
```

Debugging

Enable debug mode in config:
```
'debug' => env('APP_DEBUG', false),
```
Check storage/logs/laravel.log for storage-related errors.
Modal Not Appearing? Verify the plugin is registered in AdminPanelProvider, the ⚙️ icon is visible in the topbar, and no visible() callback is returning false.
Section missing after a fluent call? You probably disabled it — grep your panel provider for disable… calls before filing a bug.
Font applied in the preview but not on save? Reload the page fully; theme CSS is injected on render and the persisted value may only apply on the next boot.

Extension Points

Custom Colors/Fonts Extend the config arrays or pass them fluently:

'primary_colors' => [
    '#3b82f6', // Default blue
    '#10b981', // Custom green
    '#8b5cf6', // Custom purple
],

Override Default Views
```
php artisan vendor:publish --tag="filament-ui-switcher-views"
```
Useful if you need to reorder sections or add your own control to the modal.

API Integration

$preferences = FilamentUISwitcher::getPreferences();
FilamentUISwitcher::setPreferences($newPrefs);

Handy for onboarding wizards or syncing a user's theme across panels.

Upgrade Note (v1.1.1 → v1.1.2) Additive release — local font support plus fluent section toggles. No breaking changes reported, and existing config-file settings still work, so the upgrade is safe to ship without code changes. Only act if you want local fonts or finer-grained control over which sections appear.

Filament Ui Switcher Laravel Package