Download the PHP package asignua/filament-themes without Composer

Filament Themes

A theme switcher for Filament 5. Users open Themes in the user menu, pick a theme from cards that preview it in light and dark mode, and optionally replace its primary colour with a Filament colour or any #rrggbb. The choice is saved per user (or once for the whole panel) and applies on the next page. Six themes ship in the box - Default, Nord, Dracula, Sunset, Ocean, Forest - and your own is one small PHP class. It is the successor of hasnayeen/themes, which stopped before Filament 5, with the same plugin and contract names, so the PHP side of a panel migrates by swapping a namespace - but a theme's stylesheet does not carry over (see Migrating).

No JavaScript to build, no Tailwind safelist: a theme is a set of colour palettes that Filament already understands (primary, gray, danger, ...) plus an optional stylesheet, and the picker has its own namespaced CSS (.fi-themes*). Free (MIT), there is no Pro edition.

Screenshots

The theme picker: six built-in themes, each for light and dark mode:

The same table in Nord, Sunset and Dracula (dark):

Any accent colour — a Filament palette or your own hex:

Requirements

• PHP 8.3+
• Laravel 12 or 13
• Filament 5

Installation

Register the plugin on your panel. Nothing else is needed: no middleware, no theme file, no build step.

A Themes item appears in the user menu. The same page is at /{panel}/themes.

Usage

Every setter works per panel, so an admin panel and a shop panel can offer different themes and keep separate choices.

Per user or for the whole panel

In user mode guests and the login page get the panel default, and everybody signed in may change their own theme. In global mode nobody may change it until you say who (one choice restyles the panel for everybody, so it is deny by default):

What the page shows

• A card per theme with a light and a dark preview strip, the semantic colours (primary, success, warning, danger) and a short description. The current theme is marked and aria-pressed.
• For a theme that allows it (see HasChangeableColor), a row of colour swatches, a native colour input with a #rrggbb field and a "reset to the theme colour" button.
• Everything is keyboard- and screen-reader-friendly: cards and swatches are real buttons with labels and focus rings.

The new look needs a full reload (colours live in the document head), so choosing something redirects to the page itself with a success toast.

Where it is stored

The default is a small table, theme_settings, created by a publishable migration - the less invasive choice: nothing is added to your users table, it works with any authenticatable model (integer, UUID or ULID keys), it also holds the panel-wide row of global mode, and one panel can have several users with different choices.

The unique index is 992 bytes with utf8mb4 (fits MySQL's 3072 and the old 767-per-column rules; a test computes it from the migration).

Coming from hasnayeen/themes, keep your users.theme / users.theme_color columns instead:

The panel-wide global choice always uses the table. Note that these two columns belong to the user, not to a panel: with 'storage' => 'users' a user who has several panels with this plugin shares ONE choice between them (the table storage keeps a choice per panel).

Built-in themes

Each one is a hue/chroma for the primary, info, success, warning and danger colours and for the gray ladder (which tints the panel surfaces, borders and text), so every theme works in light and in dark mode. The palettes come from one lightness ladder, which is what makes the contrast guaranteed instead of hoped for; unit tests enforce WCAG AA (4.5:1) for:

• white text on the solid primary button (primary-600, used in light and dark mode) and on every other accent;
• body and muted text on the gray surfaces in light mode (gray-950 / gray-500 on gray-50, on white) and dark mode (white / gray-400 on gray-950, gray-900, gray-800);
• links (primary-600 on white, primary-400 on gray-900);
• the button of any colour a user types in, for every hue.

A colour given as a hex string - in getThemeColor() or typed by a user - is turned into a palette from its hue and chroma (chroma is capped, lightness is the ladder's), so a neon #00ff00 cannot produce an unreadable button. Named Filament palettes are used as Filament ships them - and Filament itself picks a readable text shade for them.

Writing your own theme

The class is checked when registered: anything that is not a Theme throws an InvalidArgumentException.

Optional behaviour is opt-in through small interfaces (all in Asignua\FilamentThemes\Contracts):

Or extend Themes\PaletteTheme and return one [hue, chroma] pair per colour from hues() - you get the same contrast guarantees as the built-in themes, HasChangeableColor and a translated label for free.

The stylesheet

A theme's CSS is registered as a Filament asset (published by php artisan filament:assets) and loaded on every page of the panel, so scope it to your theme. The plugin prints <meta name="filament-theme" content="midnight"> into the head:

A relative getPath() (hasnayeen themes return Vite entries such as resources/css/themes/x.css) is resolved against base_path(); a path that is not a file is skipped with a log warning. The file must be plain CSS: a Tailwind/PostCSS source is not compiled here.

Use Filament's variables (--primary-600, --gray-50, --danger-500, ...), they carry the chosen palette and flip with dark mode. Do not use Tailwind classes in this file: the panel's stylesheet only contains the classes it compiled. If you use @layer (the built-in file does: everything is in @layer components, so a utility class such as rounded-full still wins), the file must begin with @layer theme, base, components, utilities;, otherwise Tailwind's preflight in the panel loses to your layer.

Configuration

Everything is a fluent setter on the plugin; the file is only for defaults (php artisan vendor:publish --tag=filament-themes-config).

Migrating from hasnayeen/themes

Replace Hasnayeen\Themes\ with Asignua\FilamentThemes\ in your imports and remove SetTheme from the panel's middleware (it is optional now, see below). Your own theme classes keep working, but their CSS does not: hasnayeen themes ship a Tailwind/PostCSS source compiled by your Vite build and scoped to its own markup. Rewrite it as plain CSS scoped with :root:has(meta[name='filament-theme'][content='<name>']) (see "The stylesheet"), or return null from getPath() and keep only the colours. To keep the existing choices run with 'storage' => 'users'; to move to the table, copy users.theme / users.theme_color into theme_settings once.

Octane and long-lived workers

The choice is read per request (memoised on the request, never on the plugin) and Filament's colour registry is request-scoped, so one user's colours cannot leak into the next request. The one thing that outlives a request is the panel object, which CanModifyPanelConfig::modifyPanelConfig() mutates: the plugin takes a snapshot of the panel's properties before the hook and puts them back when the request terminates (a test runs two sequential requests). It is a shallow restore - an object the hook mutates in place (a plugin instance, say) is not restored - and it has been tested with sequential requests in one process, not under a real Octane server.

Gotchas

• A hex given as the gray colour gets a neutral ladder (hue kept, chroma capped at 0.03), every other hex an accent ladder (chroma capped at 0.19). defaultColor() must be one of colors() or, with customColor() on, a #rrggbb; anything else throws when the plugin is registered instead of being ignored silently.
• Colours are read when the page renders, not when the plugin boots - the session is not started yet at boot. That is why no middleware is needed, and why a panel that renders colours before authentication (for example a custom login page that resolves FilamentColor early) shows the panel default.
• Do not put ->colors([...]) of the panel and a theme in competition for the same name unless you mean it: the theme is registered last and wins. Default registers nothing, so the panel's own ->colors() stay.
• The stylesheet is global. All themes' CSS is loaded on every request; the :has(meta[name='filament-theme']) scope is what keeps it dormant. :has() needs a 2023+ browser (Chrome/Edge 105, Safari 15.4, Firefox 121); an older browser still gets the colours (they are CSS variables) but not the radius and sidebar details.
• Run php artisan filament:assets after install and after an update. Without it the picker is unstyled (the themes themselves are colour variables and do not need it).
• The index lengths of a SQLite test database prove nothing about MySQL; the migration keeps the unique key under 1000 bytes and a test computes the sum from the migration source.

Translations

The interface ships in English, Ukrainian, German, Spanish, French, Italian, Dutch, Polish, Brazilian Portuguese and Turkish under the filament-themes::filament-themes namespace (including the names and descriptions of the built-in themes: themes.nord, descriptions.nord, ...). A test keeps every language in step with the English keys. Override a string by publishing the translations (--tag=filament-themes-translations) and editing the copy in lang/vendor/filament-themes. A custom theme without a HasLabel shows its name headlined, and without a descriptions.<name> key shows no description.

AI agents

The package ships Laravel Boost guidelines (resources/boost/guidelines/core.blade.php) so a coding agent wires it up correctly.

Testing

Try it by hand with the workbench (a demo panel with products and orders in every theme):

Seed the demo user and rows with vendor/bin/testbench db:seed --class='Workbench\Database\Seeders\DemoSeeder', log in at /admin as [email protected] / password and open Themes in the user menu.

Changelog

See CHANGELOG.md.

License

The MIT License (MIT). See LICENSE.md.