Filament UI Switcher

https://github.com/andreia/filament-ui-switcher
Admin
A Filament plugin that allows users to switch between available layouts and customize UI settings...
Tokens:6,016
Snippets:52
Trust Score:9.9
License:MIT
Update:9 months ago
Show doc for...
Tokens:
Raw
### Install Filament UI Switcher Package (Bash)

Source: https://context7.com/andreia/filament-ui-switcher/llms.txt

Installs the Filament UI Switcher package using Composer and publishes necessary assets and configuration files for the Filament admin panel.

```bash
composer require andreia/filament-ui-switcher

php artisan filament:assets

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

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

php artisan vendor:publish --tag=filament-ui-switcher-views
```

--------------------------------

### Setup Database Storage for UI Preferences (Bash)

Source: https://context7.com/andreia/filament-ui-switcher/llms.txt

This section outlines the steps to configure persistent database storage for UI preferences. It involves publishing and running migrations, adding the HasUiPreferences trait to the User model, and updating the package's configuration file or environment variables.

```bash
# Step 1: Publish and run migration
php artisan vendor:publish --tag=filament-ui-switcher-migrations
php artisan migrate
```

--------------------------------

### Install Filament UI Switcher via Composer

Source: https://github.com/andreia/filament-ui-switcher/blob/main/README.md

Installs the Filament UI Switcher package using Composer. This command fetches the latest version of the package and adds it to your project's dependencies.

```bash
composer require andreia/filament-ui-switcher
```

--------------------------------

### Get UI Preference Programmatically

Source: https://github.com/andreia/filament-ui-switcher/blob/main/README.md

Demonstrates how to retrieve a specific UI preference value programmatically using the `UiPreferenceManager`. A default value can be provided if the preference is not set.

```php
use Andreia\FilamentUiSwitcher\Support\UiPreferenceManager;

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

--------------------------------

### Get User's UI Preference (Database Storage)

Source: https://github.com/andreia/filament-ui-switcher/blob/main/README.md

Retrieves a specific UI preference for the currently authenticated user when using database storage. It utilizes the `getUiPreference` method provided by the `HasUiPreferences` trait.

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

--------------------------------

### Manage UI Preferences with HasUiPreferences Trait (PHP)

Source: https://context7.com/andreia/filament-ui-switcher/llms.txt

The HasUiPreferences trait provides methods for getting and setting UI preferences directly on a User model when using database storage. It requires the 'ui_preferences' cast to be set as an 'array' in the User model's casts. This allows for easy retrieval and updating of preferences.

```php
<?php

namespace App\Models;

use Andreia\FilamentUiSwitcher\Models\Traits\HasUiPreferences;
use Illuminate\Foundation\Auth\User as Authenticatable;

class User extends Authenticatable
{
    use HasUiPreferences;

    protected function casts(): array
    {
        return [
            'email_verified_at' => 'datetime',
            'password' => 'hashed',
            'ui_preferences' => 'array', // Required for database storage
        ];
    }
}

// Usage in controllers or services:
$user = auth()->user();

// Get a specific preference with default fallback
$font = $user->getUiPreference('ui.font', 'Inter');
// Returns: 'Inter'

$color = $user->getUiPreference('ui.color', '#6366f1');
// Returns: '#6366f1'

$layout = $user->getUiPreference('ui.layout', 'sidebar');
// Returns: 'sidebar'

// Set preferences (automatically saves to database)
$user->setUiPreference('ui.font', 'Roboto');
$user->setUiPreference('ui.color', '#ef4444');
$user->setUiPreference('ui.layout', 'topbar');
$user->setUiPreference('ui.font_size', 18);

// The trait stores preferences in the ui_preferences JSON column:
// {
//     "ui.font": "Roboto",
//     "ui.color": "#ef4444",
//     "ui.layout": "topbar",
//     "ui.font_size": 18
// }
```

--------------------------------

### Publish and Run Filament UI Switcher Migrations

Source: https://github.com/andreia/filament-ui-switcher/blob/main/README.md

Publishes the necessary migration file for the Filament UI Switcher plugin and then runs the migration to add the `ui_preferences` JSON column to the users table, enabling database storage for user preferences.

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

--------------------------------

### Configure UI Switcher Options (PHP)

Source: https://context7.com/andreia/filament-ui-switcher/llms.txt

This PHP configuration file defines all available options for customizing the UI switcher's behavior, including storage drivers, default preferences, available fonts, color palettes, layouts, and font size ranges. It utilizes environment variables for driver selection.

```php
<?php

// config/ui-switcher.php
return [
    /*
    |--------------------------------------------------------------------------
    | Storage Driver
    |--------------------------------------------------------------------------
    | Options: 'session' (default), 'database'
    */
    'driver' => env('UI_SWITCHER_DRIVER', 'session'),

    /*
    |--------------------------------------------------------------------------
    | Database Column (only for database driver)
    |--------------------------------------------------------------------------
    */
    'database_column' => 'ui_preferences',

    /*
    |--------------------------------------------------------------------------
    | Default Preferences
    |--------------------------------------------------------------------------
    */
    'defaults' => [
        'font' => 'Inter',
        'color' => '#6366f1',
        'layout' => 'sidebar',
        'font_size' => 16,
        'density' => 'default',
    ],

    /*
    |--------------------------------------------------------------------------
    | Settings Icon
    |--------------------------------------------------------------------------
    */
    'icon' => 'heroicon-o-cog-6-tooth',

    /*
    |--------------------------------------------------------------------------
    | Available Fonts (Google Fonts)
    |--------------------------------------------------------------------------
    */
    'fonts' => [
        'Inter',
        'Poppins',
        'Public Sans',
        'DM Sans',
        'Nunito Sans',
        'Roboto',
        // Add custom fonts:
        // 'Montserrat',
        // 'Open Sans',
        // 'Lato',
    ],

    /*
    |--------------------------------------------------------------------------
    | Color Palette
    |--------------------------------------------------------------------------
    */
    'custom_colors' => [
        '#6366f1', // Indigo
        '#3b82f6', // Blue
        '#0ea5e9', // Sky
        '#10b981', // Emerald
        '#22c55e', // Green
        '#84cc16', // Lime
        '#eab308', // Yellow
        '#f59e0b', // Amber
        '#f97316', // Orange
        '#ef4444', // Red
        '#ec4899', // Pink
        '#8b5cf6', // Violet
        // Add brand colors:
        // '#1DB954', // Spotify Green
        // '#FF6B6B', // Custom Red
    ],

    /*
    |--------------------------------------------------------------------------
    | Available Layouts
    |--------------------------------------------------------------------------
    */
    '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
    ],

    /*
    |--------------------------------------------------------------------------
    | Font Size Range (pixels)
    |--------------------------------------------------------------------------
    */
    'font_size_range' => [
        'min' => 12,
        'max' => 20,
    ],
];

```

--------------------------------

### Configure Filament UI Switcher Plugin Options (PHP)

Source: https://context7.com/andreia/filament-ui-switcher/llms.txt

Demonstrates various ways to configure the Filament UI Switcher plugin, including setting the icon render hook and enabling the mode switcher for dark/light/system toggles.

```php
<?php

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

// Basic registration
->plugin(FilamentUiSwitcherPlugin::make())

// With custom icon position (after user menu instead of before)
->plugin(
    FilamentUiSwitcherPlugin::make()
        ->iconRenderHook(PanelsRenderHook::USER_MENU_AFTER)
)

// With mode switcher enabled (dark/light/system toggle)
->plugin(
    FilamentUiSwitcherPlugin::make()
        ->withModeSwitcher()
)

// Full configuration example
->plugin(
    FilamentUiSwitcherPlugin::make()
        ->iconRenderHook(PanelsRenderHook::TOPBAR_END)
        ->withModeSwitcher(true)
)

// Available render hooks for icon position:
// - PanelsRenderHook::USER_MENU_BEFORE (default)
// - PanelsRenderHook::USER_MENU_AFTER
// - PanelsRenderHook::TOPBAR_START
// - PanelsRenderHook::TOPBAR_END
// - PanelsRenderHook::GLOBAL_SEARCH_BEFORE
// - PanelsRenderHook::GLOBAL_SEARCH_AFTER
```

--------------------------------

### Publish Filament UI Switcher Configuration and Translations

Source: https://github.com/andreia/filament-ui-switcher/blob/main/README.md

Publishes the configuration file and translation files for the Filament UI Switcher plugin. This allows for customization of default settings, available fonts, custom colors, and more.

```bash
php artisan vendor:publish --tag=filament-ui-switcher-config
```

```bash
php artisan vendor:publish --tag=filament-ui-switcher-translations
```

--------------------------------

### Run Composer Tests

Source: https://github.com/andreia/filament-ui-switcher/blob/main/README.md

Executes the test suite for the Filament UI Switcher package using Composer. This command is used to verify the functionality and stability of the plugin.

```bash
composer test
```

--------------------------------

### Available Layouts Configuration

Source: https://github.com/andreia/filament-ui-switcher/blob/main/README.md

Specifies which navigation layout options are available to users. This allows you to control the different ways users can interact with the Filament interface.

```php
'layouts' => [
    'sidebar',
    'sidebar-collapsed',
    'sidebar-no-topbar', // Filament v4.1+
    'topbar',
],
```

--------------------------------

### Configure UI Switcher Driver to Database (PHP)

Source: https://context7.com/andreia/filament-ui-switcher/llms.txt

To enable database storage for UI preferences, you need to modify the configuration file `config/ui-switcher.php` or set the corresponding environment variable. Ensure the 'driver' is set to 'database' and specify the 'database_column' where preferences will be stored.

```php
<?php

// Step 3: Update config/ui-switcher.php
return [
    'driver' => 'database', // Changed from 'session'
    'database_column' => 'ui_preferences',
    // ... rest of config
];

// Or set via environment variable in .env:
// UI_SWITCHER_DRIVER=database
```

--------------------------------

### Publish Filament UI Switcher Views (Optional)

Source: https://github.com/andreia/filament-ui-switcher/blob/main/README.md

Optionally publishes the view files for the Filament UI Switcher plugin. This allows for deep customization of the plugin's user interface elements.

```bash
php artisan vendor:publish --tag=filament-ui-switcher-views
```

--------------------------------

### Build Theme Assets (Bash)

Source: https://context7.com/andreia/filament-ui-switcher/llms.txt

This bash command rebuilds your theme assets after making changes to your CSS files, ensuring that the UI switcher's styles and TailwindCSS classes are correctly compiled and applied.

```bash
# Build your theme assets
npm run build

```

--------------------------------

### Configure UI Switcher Storage Driver

Source: https://github.com/andreia/filament-ui-switcher/blob/main/README.md

Defines the storage mechanism for UI preferences. Options include 'session' (default) for temporary storage or 'database' for persistent user-specific storage.

```php
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',
];
```

--------------------------------

### Publish Filament Assets

Source: https://github.com/andreia/filament-ui-switcher/blob/main/README.md

Publishes the necessary assets for the Filament UI Switcher plugin. This command ensures that the plugin's CSS and other assets are correctly placed in your project's public directory for Filament to load.

```bash
php artisan filament:assets
```

--------------------------------

### Retrieve UI Preference with UiPreferenceManager (PHP)

Source: https://context7.com/andreia/filament-ui-switcher/llms.txt

Shows how to retrieve UI preference values like font, color, layout, font size, and density using the `UiPreferenceManager` class, with fallback defaults.

```php
<?php

use Andreia\FilamentUiSwitcher\Support\UiPreferenceManager;

// Get current font preference with fallback default
$font = UiPreferenceManager::get('ui.font', 'Inter');
// Returns: 'Inter', 'Poppins', 'Roboto', etc.

// Get current primary color
$color = UiPreferenceManager::get('ui.color', '#6366f1');
// Returns: '#6366f1', '#3b82f6', '#10b981', etc.

// Get current layout preference
$layout = UiPreferenceManager::get('ui.layout', 'sidebar');
// Returns: 'sidebar', 'sidebar-collapsed', 'sidebar-no-topbar', 'topbar'

// Get current font size
$fontSize = UiPreferenceManager::get('ui.font_size', 16);
// Returns: 12-20 (integer)

// Get current density setting
$density = UiPreferenceManager::get('ui.density', 'default');
// Returns: 'default' or custom density value

// Example: Apply preferences in a custom component
$currentFont = UiPreferenceManager::get('ui.font', config('ui-switcher.defaults.font'));
$currentColor = UiPreferenceManager::get('ui.color', config('ui-switcher.defaults.color'));
```

--------------------------------

### Set UI Preference Programmatically

Source: https://github.com/andreia/filament-ui-switcher/blob/main/README.md

Shows how to set or update a UI preference programmatically using the `UiPreferenceManager`. This allows dynamic modification of user interface settings.

```php
use Andreia\FilamentUiSwitcher\Support\UiPreferenceManager;

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

--------------------------------

### Available Fonts Configuration

Source: https://github.com/andreia/filament-ui-switcher/blob/main/README.md

Specifies the list of Google Fonts available for users to select from. You can add or remove fonts from this array to customize the font picker options.

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

--------------------------------

### Default Preferences Configuration

Source: https://github.com/andreia/filament-ui-switcher/blob/main/README.md

Defines the default settings for the UI switcher, including font family, primary color, layout, font size, and UI density. These values are used when no user preferences are set.

```php
'defaults' => [
    'font' => 'Inter',
    'color' => '#6366f1',
    'layout' => 'sidebar',
    'font_size' => 16,
    'density' => 'default',
],
```

--------------------------------

### Integrate UI Switcher Theme (CSS)

Source: https://context7.com/andreia/filament-ui-switcher/llms.txt

This CSS snippet integrates the UI switcher's vendor directory into your custom Filament theme, ensuring proper TailwindCSS class support. It imports the default Filament theme and then sources the UI switcher's assets.

```css
/* resources/css/filament/admin/theme.css */
@import '/vendor/filament/filament/resources/css/theme.css';

/* Add UI Switcher vendor directory for TailwindCSS classes */
@source '../../../../vendor/andreia/filament-ui-switcher';

/* Your custom styles */

```

--------------------------------

### Register UI Switcher Plugin (PHP)

Source: https://context7.com/andreia/filament-ui-switcher/llms.txt

This PHP code registers the Filament UI Switcher plugin within your Filament panel configuration. It ensures the plugin is loaded and active for your admin panel, utilizing your custom theme.

```php
<?php

// app/Providers/Filament/AdminPanelProvider.php
use Filament\Panel;

public function panel(Panel $panel): Panel
{
    return $panel
        ->id('admin')
        ->path('admin')
        // Use your custom theme
        ->viteTheme('resources/css/filament/admin/theme.css')
        ->plugin(FilamentUiSwitcherPlugin::make());
}

```

--------------------------------

### Add HasUiPreferences Trait to User Model

Source: https://github.com/andreia/filament-ui-switcher/blob/main/README.md

Integrates the `HasUiPreferences` trait and a `'ui_preferences' => 'array'` cast into your `User` model to support database storage of UI preferences. This allows preferences to persist across sessions and devices.

```php
use Andreia\FilamentUiSwitcher\Models\Traits\HasUiPreferences;

class User extends Authenticatable
{
    use HasUiPreferences;

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

--------------------------------

### Custom Colors Configuration

Source: https://github.com/andreia/filament-ui-switcher/blob/main/README.md

Defines the color palette that will be displayed in the color picker. This allows you to set predefined brand colors or a selection of appealing color options for users.

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

--------------------------------

### Font Size Range Configuration

Source: https://github.com/andreia/filament-ui-switcher/blob/main/README.md

Defines the minimum and maximum values for the font size slider. This controls the range of font sizes users can select for the application's interface.

```php
'font_size_range' => [
    'min' => 12,
    'max' => 20,
],
```

--------------------------------

### Custom UI Icon Configuration

Source: https://github.com/andreia/filament-ui-switcher/blob/main/README.md

Sets the icon used to trigger the UI settings modal. You can use any valid Heroicon name to customize the appearance of the settings trigger.

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

--------------------------------

### Customize Icon Position in Filament UI Switcher

Source: https://github.com/andreia/filament-ui-switcher/blob/main/README.md

Allows customization of the settings icon's position on the topbar using Filament's render hooks. By default, it appears before the user menu. You can specify different locations like TOPBAR_END, TOPBAR_START, etc.

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

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

--------------------------------

### Set User's UI Preference (Database Storage)

Source: https://github.com/andreia/filament-ui-switcher/blob/main/README.md

Sets or updates a UI preference for the currently authenticated user when using database storage. This is achieved through the `setUiPreference` method from the `HasUiPreferences` trait.

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

--------------------------------

### Set UI Preferences using UiPreferenceManager (PHP)

Source: https://context7.com/andreia/filament-ui-switcher/llms.txt

The UiPreferenceManager::set() method allows you to store UI preference values. It can store preferences to session or database, depending on the package's configuration. This method is useful for setting individual preferences like font, color, layout, font size, and density.

```php
<?php

use Andreia\FilamentUiSwitcher\Support\UiPreferenceManager;

// Set font preference
UiPreferenceManager::set('ui.font', 'Poppins');

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

// Set layout
UiPreferenceManager::set('ui.layout', 'topbar');

// Set font size (12-20 pixels)
UiPreferenceManager::set('ui.font_size', 14);

// Set density
UiPreferenceManager::set('ui.density', 'compact');

// Example: Programmatically set multiple preferences
UiPreferenceManager::set('ui.font', 'DM Sans');
UiPreferenceManager::set('ui.color', '#3b82f6');
UiPreferenceManager::set('ui.layout', 'sidebar-collapsed');
UiPreferenceManager::set('ui.font_size', 15);
```

--------------------------------

### Enable Mode Switcher in Filament UI Switcher

Source: https://github.com/andreia/filament-ui-switcher/blob/main/README.md

Enables the native Filament mode switcher (light, dark, system) within the settings modal. This is an optional feature that can be activated using the `->withModeSwitcher()` method.

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

--------------------------------

### Register Filament UI Switcher Plugin in Panel Provider

Source: https://github.com/andreia/filament-ui-switcher/blob/main/README.md

Registers the Filament UI Switcher plugin within your Filament Panel Provider. This step is crucial for enabling the plugin's functionality within your Filament application.

```php
use Andreia\FilamentUiSwitcher\FilamentUiSwitcherPlugin;

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

--------------------------------

### Add UI Switcher Path to Theme CSS

Source: https://github.com/andreia/filament-ui-switcher/blob/main/README.md

Integrates the Filament UI Switcher's additional TailwindCSS classes into your custom Filament theme. This involves adding a `@source` directive to your `theme.css` file and rebuilding your assets.

```css
/* ... */

@source '../../../../vendor/andreia/filament-ui-switcher';
```
Tokens:
Raw