Filament Flux Theme

The Flux design language for your Filament v5 panel.

Flat surfaces. Monochrome accents. Zinc neutrals. The clean, considered look of Livewire's official component library — dropped onto your admin panel in five minutes, with zero Blade overrides and nothing for Filament updates to break.

Filament is the fastest way to build admin panels in Laravel. Flux is the design language behind Livewire's official component library — flat, monochrome, accessible, and quietly beautiful out of the box. This package marries the two.

It's a CSS-first theme plugin that retints and reshapes your existing Filament markup to match Flux — no component swaps, no published views, no fighting the framework. You keep every bit of Filament's speed and reliability, and your panel comes out looking like it was designed, not assembled.

->plugin(FluxTheme::make()->accent('zinc'))

One line. That's the whole API for the default look.

Why you'll like it

• 🎨 Looks designed, not bolted on. Flat surfaces flush with the page, hairline dividers instead of heavy shadows, and a monochrome accent that reads as intentional. Light and dark mode both, with no extra work.
• ⚡ CSS-first, zero overhead. No migrations, no jobs, no commands, no runtime cost. It's a stylesheet and a handful of CSS variables — it ships nothing that can slow a request down.
• 🧩 Future-proof by design. Pure .fi-* selectors and Tailwind v4 tokens. There are no Blade overrides to drift out of sync, so Filament can ship updates and your theme keeps working.
• 🎚️ Yours to tune. Stay monochrome, drop in any Tailwind ramp, paste a pick straight from fluxui.dev/themes, or hand it a raw oklch(). Per-panel, per-environment, or from .env.
• 🧹 Clean in, clean out. composer remove plus deleting one @import line returns your panel to stock Filament with zero leftovers. No residue, no regrets.

What "the Flux look" means

If you've used Flux, you already know the feel. In plain terms:

• Flat — surfaces sit flush with the page background instead of floating on raised cards.
• Monochrome accent — by default the highlight color (buttons, active links) is near-black in light mode and near-white in dark mode, rather than a bright brand color. Swap in a real hue (blue, rose, violet…) whenever you want.
• Zinc neutrals — grays come from Tailwind's zinc palette — a clean, slightly cool gray — used consistently everywhere.
• Minimal shadows — very little drop-shadow or glow; the design leans on spacing and subtle hairlines instead.

New to Filament? Here's the lay of the land. Filament is a toolkit for building admin panels in Laravel — the dashboards, tables, and forms behind your app. A panel is one of those admin areas (often at /admin); you can have more than one. A theme plugin is a small add-on you register on a panel to change how it looks, without touching what it does. This package is exactly that.

Requirements

This is a modern, CSS-first theme built for the current stack: it uses Tailwind v4's @theme token layer and Filament v5's viteTheme() API. That's what keeps it lightweight and update-proof — but it also means it will not work on older PHP, Tailwind v3, or Filament v3/v4 setups. Check your versions (php -v, and your app's composer.json) before you start.

Before you start: this guide assumes you already have a working Laravel app with Filament v5 installed and at least one panel (created via php artisan filament:install --panels), plus Node.js / npm and Vite (the default for a fresh Laravel app). If you don't have a panel yet, set that up first — see the Filament installation docs. Run all commands below from your Laravel application's root directory (where its composer.json lives), unless stated otherwise.

Installation

Follow the steps in order — most install problems come from skipping the asset rebuild (Step 5) or getting the CSS import path wrong (Step 3).

Step 1 — Require the package via Composer

This package is served over Private Packagist, not the public Packagist.org index — so a plain composer require alwayscurious/filament-flux-theme won't resolve until you register the repository and add your access token. Composer needs both the repository location and a token to reach it.

1. Register the repository (Composer 2.9+):

   composer config repositories.private-packagist composer https://repo.packagist.com/alwayscurious/
   

   This adds the following to your composer.json:

   "repositories": [
       {
           "type": "composer",
           "url": "https://repo.packagist.com/alwayscurious/"
       }
   ]
   

2. Add your auth token (kept out of git, stored in auth.json):

   composer config --auth http-basic.repo.packagist.com token <YOUR_PRIVATE_PACKAGIST_TOKEN>
   

3. Require the package:

   composer require alwayscurious/filament-flux-theme
   

Common mistake: Committing the token, or forgetting it entirely and seeing ... file could not be downloaded (HTTP/2 403). A 403 is an auth problem, not a "package missing" problem. Add auth.json to .gitignore, or set the token in CI via the COMPOSER_AUTH environment variable.

Step 2 — Scaffold the panel's theme CSS

Why: Filament ships precompiled default CSS. To layer a custom theme on top, you need to own a CSS entry point and compile it through Vite. This command creates that entry point and helps wire it up.

Run Filament's theme generator, naming your panel (admin here):

php artisan make:filament-theme admin

This creates resources/css/filament/admin/theme.css. It then usually prints the exact lines to add to vite.config.js (a new entry in the input array) and to your panel provider (->viteTheme(...)) — follow whatever the command prints on screen. Depending on your Filament version it may make those edits for you or ask you to add them by hand; either is fine. If it asks which panel, choose admin.

Note: The panel name (admin) must match your actual panel ID. The generated path mirrors it: resources/css/filament/<panel>/theme.css.

Step 3 — Import the package stylesheet

Why the order matters: CSS applies later rules on top of earlier ones. The Flux theme is an overlay that overrides Filament's tokens and component styles — so it must come after Filament's base import, or Filament's defaults will load afterward and cancel out the Flux look.

Open resources/css/filament/admin/theme.css and add the package @import after the line that imports Filament's base theme:

@import '../../../../vendor/filament/filament/resources/css/theme.css';

/* filament-flux-theme overlay — MUST come after Filament's base theme above.
   Remove this line if you uninstall the package, or Vite will fail to resolve it. */
@import '../../../../vendor/alwayscurious/filament-flux-theme/resources/css/theme.css';

@source '../../../../app/Filament';
@source '../../../../resources/views';

Why exactly four ../: theme.css lives four folders deep (resources/css/filament/admin/), so four ../ climb back to the project root before descending into vendor/. A wrong depth (three or five ../) produces a Vite build error like Failed to resolve import.

Step 4 — Register the plugin on your panel

Why: The CSS import only restyles surfaces; the plugin is what configures Filament's primary/gray color palettes and emits the Flux accent variables. The class_exists guard means that if you ever composer remove the package, this block silently no-ops instead of throwing a "class not found" fatal error.

Open app/Providers/Filament/AdminPanelProvider.php. You'll find a panel() method that already has a return $panel->... chain. Append the ->when(...) block to that existing chain, immediately before its closing ; — don't add a second return:

use Filament\Panel;

public function panel(Panel $panel): Panel
{
    return $panel
        // ...your existing panel config...
        ->viteTheme('resources/css/filament/admin/theme.css')
        ->when(
            class_exists(\AlwaysCurious\FilamentFluxTheme\FluxTheme::class),
            fn (Panel $panel) => $panel->plugin(
                \AlwaysCurious\FilamentFluxTheme\FluxTheme::make()->accent('zinc'),
            ),
        );
}

If you don't care about clean uninstalls, the simpler form works too — same existing return $panel chain, just a plain ->plugin(...):

use AlwaysCurious\FilamentFluxTheme\FluxTheme;

return $panel
    ->viteTheme('resources/css/filament/admin/theme.css')
    ->plugin(FluxTheme::make()->accent('zinc'));

Note: Step 2 should already have added the ->viteTheme(...) call — just confirm it's there rather than adding it twice, then append the plugin block.

Step 5 — Build your assets

Why: Everything above is source. Filament serves compiled CSS through Vite, so until you rebuild, the browser keeps serving the old stylesheet and the theme will appear to "do nothing." This is the single most common mistake.

Compile your assets:

npm run build

Or, while actively developing, run the watcher instead:

npm run dev

Tip: If you've never built this project's front end before, run npm install first. Any time you change theme.css or a theme option, rebuild (or keep npm run dev running).

Quick install checklist

1. Confirm PHP ^8.3, Laravel ^11+, Filament ^5, Tailwind ^4, and an existing panel.
2. Register the Private Packagist repository, add your token, and composer require the package.
3. php artisan make:filament-theme admin.
4. Add the package @import to resources/css/filament/admin/theme.css, after Filament's base, with exactly four ../.
5. Register FluxTheme::make()->accent('zinc') on the panel with the class_exists guard.
6. npm run build (or npm run dev).

What gets styled

Every surface in your panel, reskinned to match Flux — and nothing more. This theme ships one extra stylesheet that retints and reshapes Filament's existing markup. There are no Blade overrides, no published views, and no component swaps — which is exactly why it stays compatible across Filament updates. Everything below applies to both light and dark mode.

Configuration

This section walks you from the fastest setup to full control. Start at the top; only keep reading until your needs are met.

The snippets below show only the plugin call for brevity. In your real panel provider, keep the ->viteTheme(...) and the class_exists() guard from Installation Step 4 — just swap in the FluxTheme::make()->... part shown in each snippet.

1. The quick way

The simplest setup picks one accent color:

FluxTheme::make()->accent('zinc')

FluxTheme::make() creates the plugin and reads its starting values from config. ->accent('zinc') picks one of the legacy accent colors. Valid names are:

zinc, slate, stone, neutral, emerald, sky, rose, amber, violet, indigo, teal

Stick to the names on this list. An unrecognized name doesn't cleanly fall back — Filament's primary/gray palettes default to the zinc base (so the panel looks roughly zinc), but the runtime --color-accent CSS variable receives your invalid string verbatim and produces no usable accent color. When in doubt, use the full theme([...]) generator (section 4) instead.

The config file

Prefer to set defaults app-wide? Publish the config file:

php artisan vendor:publish --tag="filament-flux-theme-config"

This gives you a config file with two simple keys (plus theme, covered in section 4):

The fourth key, theme, defaults to an empty array [] and unlocks the advanced path in section 4.

Values set in config become the defaults for every FluxTheme::make(). The fluent setters below override them per panel.

2. Per-panel fluent overrides

Every config key has a matching fluent setter, so you can override the defaults on a single panel. They