Skip to content

Overview

The theme configurator is a floating action button (bottom-right of every panel page) that opens a Livewire modal where users can:

  • Switch between presets (Glass, Aurora, Midnight, Corporate, Warm).
  • Toggle dark mode.
  • Pick a primary color from a curated palette.

Preferences persist per-user via a aura_theme_preferences JSON column on the users table, so each user sees their own theme across sessions and devices.

Installation

1. Publish and run the migration

php artisan vendor:publish --tag=aura-filament-migrations
php artisan migrate

This adds a nullable JSON column aura_theme_preferences to your users table.

2. Add the trait to your User model

use BlueStarSystem\AuraFilament\Concerns\HasAuraThemePreferences;
use Illuminate\Foundation\Auth\User as Authenticatable;

class User extends Authenticatable
{
    use HasAuraThemePreferences;

    // ...
}

The trait handles casting, reading, and persisting preferences transparently.

3. Enable the configurator on the plugin

use BlueStarSystem\AuraFilament\AuraFilamentPlugin;

AuraFilamentPlugin::make()
    ->preset(Preset::Glass)
    ->themeConfigurator()

That's it — the FAB now appears at the bottom-right of every authenticated panel page.

How it works

On every panel render, Aura Filament's body-start hook reads auth()->user()?->aura_theme_preferences and injects a tiny inline script that applies the saved preset and dark mode synchronously, before paint, so there's no flash of unstyled content.

When the user changes a setting inside the modal, the Livewire component writes to the JSON column and to localStorage for dark mode. Both sources are kept in sync so Filament's default dark-mode toggle (if you've kept it visible) still behaves correctly.

Customizing the available options

By default, all presets in the Preset enum and a curated 10-color palette are available. If you want to restrict the options (for example, only expose two presets and your brand's primary colors), you can override the relevant static properties on the configurator component in a published Livewire class. See the source AuraThemeConfigurator.php for the exact shape.

User-model gotchas

  • Do not remove the aura_theme_preferences cast — the trait sets it to array and reads it back as an array. Removing the cast will cause "Cannot convert array to string" errors.
  • Running php artisan migrate:fresh during development is fine; the column is re-added. In production, the column is additive so no data is lost.
  • If your User model uses a custom cast for attributes, make sure it doesn't clobber aura_theme_preferences.

Disabling for specific users

If you want to hide the configurator from a subset of users (for example, tenants on a read-only plan), you can conditionally call ->themeConfigurator() based on config, or override the body-start hook in your own panel provider.