README

Switch between the available Filament layouts with a customizable UI settings slideover modal accessible from a ⚙️ icon in the topbar.

Features

Customization Options:

• Primary Color - Choose from the predefined colors or add your custom colors
• Font Family - Select from 6 popular Google Fonts (Inter, Poppins, Roboto, DM Sans, Nunito Sans, Public Sans)
• Font Size - Adjust base font size (12-20px)
• Layout - Switch between Sidebar, Compact Sidebar, and Topbar navigation
• Mode (optional) - Display Filament's mode switcher (dark, light, and system)
• Reset All - Quickly reset all customizations to default values with a single click

Storage Options:

• Session Storage (default) - Preferences stored in user session
• Database Storage - Persist preferences per user in database

Requirements

• PHP 8.2 or higher
• Laravel 11.x or 12.x
• Filament 4.1+ or 5.x
• Livewire 3.x or 4.x

Note: While the plugin technically works with Filament 4.0, the "No Topbar" layout option requires Filament 4.1+. Other layout options work on all Filament 4.x versions.

Installation

1. Install via Composer

composer require andreia/filament-ui-switcher

The package will auto-register via Laravel's package discovery.

2. Publish Assets

This package uses Filament's asset management system. After installing, you need to publish the assets:

php artisan filament:assets

This will publish the CSS assets to public/css/andreia/filament-ui-switcher/ where they will be automatically loaded by Filament and cached by your browser for better performance.

Note: If you update the package, run php artisan filament:assets again to get the latest assets.

3. Publish Config

You can customize the colors, fonts, and more with the config file:

# Publish config
php artisan vendor:publish --tag=filament-ui-switcher-config

# Publish translations
php artisan vendor:publish --tag=filament-ui-switcher-translations

This will create a config/ui-switcher.php file where you can customize:

Default Preferences:

'defaults' => [
    'font' => 'Inter',           // Default font family
    'color' => '#6366f1',      // Default primary color
    'layout' => 'sidebar',       // Default layout
    'font_size' => 16,           // Default font size in pixels
    'density' => 'default',      // Default UI density
],

Available Fonts: Add or remove Google Fonts from the font picker:

'fonts' => [
    'Inter',
    'Poppins',
    'Public Sans',
    'DM Sans',
    'Nunito Sans',
    'Roboto',
    // Add any Google Font you want:
    // 'Montserrat',
    // 'Open Sans',
],

Custom Colors: Customize the color palette shown in the color picker:

'custom_colors' => [
    '#6366f1', '#3b82f6', '#0ea5e9', '#10b981',
    '#22c55e', '#84cc16', '#eab308', '#f59e0b',
    '#f97316', '#ef4444', '#ec4899', '#8b5cf6',
    // Add your brand colors:
    // '#yourBrandColor',
],

Custom UI icon: Customize the UI icon modal trigger:

'icon' => 'heroicon-o-cog-6-tooth',

Font Size Range: Set the min and max values for the font size slider:

'font_size_range' => [
    'min' => 12,  // Minimum font size in pixels
    'max' => 20,  // Maximum font size in pixels
],

Available Layouts: Control which layout options are available to users:

'layouts' => [
    'sidebar',               // Full sidebar with icons and labels
    'sidebar-collapsed',     // Collapsed sidebar (icons only)
    'sidebar-no-topbar',     // Sidebar without topbar (Filament v4.1+)
    'topbar',                // Top navigation bar
],

3. Publish View (Optional)

If you want to customize the view:

# Publish view (optional)
php artisan vendor:publish --tag=filament-ui-switcher-views

4. Register the Plugin

Add the plugin to your Filament Panel Provider (e.g., app/Providers/Filament/AdminPanelProvider.php):

use Andreia\FilamentUiSwitcher\FilamentUiSwitcherPlugin;

public function panel(Panel $panel): Panel
{
    return $panel
        ->id('admin')
        ->path('admin')
        // ... other config
        ->plugin(FilamentUiSwitcherPlugin::make());
}

Customize Icon Position

By default, the settings icon appears before the user menu (USER_MENU_BEFORE) on topbar. You can customize where the icon appears using any Filament render hook:

use Andreia\FilamentUiSwitcher\FilamentUiSwitcherPlugin;
use Filament\View\PanelsRenderHook;

->plugin(
    FilamentUiSwitcherPlugin::make()
        ->iconRenderHook(PanelsRenderHook::TOPBAR_END)
)

Available render hooks for the icon:

• PanelsRenderHook::USER_MENU_BEFORE (default) - Before the user menu
• PanelsRenderHook::USER_MENU_AFTER - After the user menu
• PanelsRenderHook::TOPBAR_START - Start of topbar
• PanelsRenderHook::TOPBAR_END - End of topbar
• PanelsRenderHook::GLOBAL_SEARCH_BEFORE - Before global search
• PanelsRenderHook::GLOBAL_SEARCH_AFTER - After global search
• Or any custom render hook you've defined

Enable Mode Switcher (Optional)

By default, the mode switcher is hidden. If you want to include Filament's native mode switcher (to switch between light, dark, and system) in the settings modal, enable it using the ->withModeSwitcher() method:

->plugin(
    FilamentUiSwitcherPlugin::make()
        ->withModeSwitcher()
)

5. Add the UI switcher path in your theme file

Filament recommends developers create a custom theme to better support plugin's additional TailwindCSS classes. After you have created your custom theme, add the UI swicher vendor directory to your theme's theme.css file usually located in resources/css/filament/admin/theme.css:

/* ... */

@source '../../../../vendor/andreia/filament-ui-switcher';

and execute:

npm run build

That's it! A ⚙️ settings icon will now appear in your topbar.

Appearance

Usage

Resetting Preferences

The settings modal includes a reset button in the header that allows users to quickly restore all customizations to their default values. When clicked, it will reset:

• Primary color
• Font family
• Font size
• Layout
• Mode (dark/light/system)

All preferences will be restored to the values defined in your config/ui-switcher.php file under the defaults key.

Configuration

The config file (config/ui-switcher.php) allows you to choose storage driver:

return [
    /*
    |--------------------------------------------------------------------------
    | Storage Driver
    |--------------------------------------------------------------------------
    | Where to store UI preferences.
    | Options: 'session' (default), 'database'
    */
    'driver' => 'session',

    /*
    |--------------------------------------------------------------------------
    | Database Column
    |--------------------------------------------------------------------------
    | Only used if driver = 'database'.
    | The column on the users table where preferences are stored as JSON.
    */
    'database_column' => 'ui_preferences',
];

Database Storage (Optional)

If you want to persist preferences per user across sessions and devices:

Step 1: Publish and Run Migration

php artisan vendor:publish --tag=filament-ui-switcher-migrations
php artisan migrate

This adds a ui_preferences JSON column to your users table.

Step 2: Add HasUiPreferences Trait to User Model

Update your User model adding the HasUiPreferences trait and a 'ui_preferences' => 'array' cast, like so:

use Andreia\FilamentUiSwitcher\Models\Traits\HasUiPreferences;

class User extends Authenticatable
{
    use HasUiPreferences;

    protected function casts(): array
    {
        return [
            // ...
            'ui_preferences' => 'array',
        ];
    }
}

Step 3: Update Config

Set the driver to database in config/ui-switcher.php:

'driver' => 'database',

Now preferences are saved per-user and persist across logins!

Programmatic Access

You can also access and modify preferences programmatically:

use Andreia\FilamentUiSwitcher\Support\UiPreferenceManager;

// Get a preference
$font = UiPreferenceManager::get('ui.font', 'Inter');

// Set a preference
UiPreferenceManager::set('ui.color', '#10b981');

If using database storage with the HasUiPreferences trait:

// Get user's preference
$font = auth()->user()->getUiPreference('ui.font', 'Inter');

// Set user's preference
auth()->user()->setUiPreference('ui.color', '#10b981');

Testing

composer test

Changelog

Please see CHANGELOG for more information on what has changed recently.

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

Security

If you discover any security related issues, please email andreiabohner@gmail.com instead of using the issue tracker.

Credits

• Andréia Bohner
• All Contributors

License

The MIT License (MIT). Please see License File for more information.

Made with ❤️ for the Filament community