Filament v4/v5 : maîtriser les thèmes avec Tailwind CSS v4 et la configuration CSS-first
Avec l'arrivée de Tailwind CSS v4 et ses évolutions majeures, la gestion des thèmes dans Filament a connu des changements concrets que tout développeur Laravel doit comprendre avant de migrer. Cet article fait le point sur ce qui change réellement, du paramétrage des couleurs jusqu'à l'injection de CSS personnalisé.
Source originale : Understanding Filament themes in v4/v5: from Colors to custom CSS — yebor974 pour Filament Mastery.
Définir les couleurs de son panel : rien ne change (ou presque)
Bonne nouvelle : la gestion des couleurs de base n'a pas bougé entre Filament v3 et v4/v5. On utilise toujours la classe Filament\Support\Colors\Color.
Par panel, dans votre provider :
use Filament\Support\Colors\Color;
public function panel(Panel $panel): Panel
{
return $panel->colors([
'danger' => Color::Rose,
'gray' => Color::Gray,
'info' => Color::Blue,
'primary' => Color::Indigo,
'success' => Color::Emerald,
'warning' => Color::Orange,
]);
}
Globalement, depuis AppServiceProvider, pour appliquer les mêmes couleurs à tous vos panels :
use Filament\Facades\Filament;
use Filament\Support\Colors\Color;
public function boot(): void
{
Filament::defaultColors([
'danger' => Color::Rose,
'primary' => Color::Indigo,
// ...
]);
}
Ces deux approches fonctionnent exactement comme avant. L'essentiel des changements se situe au niveau de la génération et de la structure des fichiers de thème.
Ce qui change vraiment : la configuration CSS-first de Tailwind v4
C'est ici que la migration demande le plus d'attention. Tailwind CSS v4 abandonne le fichier tailwind.config.js au profit d'une configuration directement dans le CSS, via des directives @theme.
Avant (Tailwind v3 / Filament v3)
Le thème généré par Filament produisait un fichier CSS minimaliste et un fichier tailwind.config.js dans lequel vous déclariez vos personnalisations :
// tailwind.config.js
module.exports = {
theme: {
extend: {
colors: {
primary: { ... }
}
}
}
}
Maintenant (Tailwind v4 / Filament v4+)
Le fichier de thème généré par la commande Filament est désormais un fichier CSS autonome qui utilise les nouvelles directives de Tailwind v4 :
@import 'tailwindcss';
@import '../../vendor/filament/filament/resources/css/theme.css';
@source '../../app/Filament';
@source '../../resources/views/filament';
@plugin '../../vendor/filament/filament/tailwind.config.preset';
@theme {
--font-family-sans: 'Inter', ui-sans-serif, system-ui, sans-serif;
--radius-sm: 0.25rem;
/* Vos variables CSS personnalisées ici */
}
Plus de tailwind.config.js à maintenir séparément : toute la configuration vit dans le CSS. C'est le principe CSS-first de Tailwind v4.
Générer le thème avec Filament
La commande reste similaire, mais le résultat produit est différent :
php artisan filament:install --theme
# ou pour un panel spécifique
php artisan make:filament-theme
Filament génère automatiquement un fichier CSS compatible Tailwind v4, prêt à être compilé avec Vite.
Personnaliser le thème : variables CSS et CSS custom
Tailwind v4 s'appuie massivement sur les custom properties CSS (variables CSS), ce qui ouvre des possibilités intéressantes pour la personnalisation de Filament.
Surcharger des variables de design
Dans le bloc @theme de votre fichier CSS, vous pouvez redéfinir les tokens de design directement :
@theme {
--color-primary-500: #6366f1;
--color-primary-600: #4f46e5;
--radius-lg: 0.75rem;
--font-family-sans: 'Inter', sans-serif;
}
Ces variables sont ensuite utilisées nativement par Tailwind et Filament dans toute l'interface.
Ajouter du CSS personnalisé
Pour aller plus loin, vous pouvez toujours injecter du CSS arbitraire après les imports Filament :
@import 'tailwindcss';
@import '../../vendor/filament/filament/resources/css/theme.css';
@plugin '../../vendor/filament/filament/tailwind.config.preset';
@theme {
--font-family-sans: 'Inter', sans-serif;
}
/* CSS personnalisé */
.fi-sidebar {
border-right: 2px solid var(--color-primary-100);
}
.fi-btn-primary {
border-radius: var(--radius-lg);
}
Le préfixe fi- est utilisé par Filament pour ses propres composants : il vous permet de cibler précisément les éléments de l'interface sans risquer de conflits.
Déclarer le thème dans le panel provider
Une fois votre fichier CSS prêt, déclarez-le dans votre panel provider :
public function panel(Panel $panel): Panel
{
return $panel
->viteTheme('resources/css/filament/admin/theme.css')
->colors([
'primary' => Color::Indigo,
]);
}
N'oubliez pas d'ajouter le point d'entrée dans votre vite.config.js :
export default defineConfig({
plugins: [
laravel({
input: [
'resources/css/app.css',
'resources/css/filament/admin/theme.css',
'resources/js/app.js',
],
refresh: true,
}),
],
});
Ce qu'il faut retenir pour une migration réussie
Si vous migrez un projet Filament v3 vers v4/v5, voici les points de vigilance :
- Supprimer
tailwind.config.js spécifique à Filament : il n'est plus nécessaire ni supporté dans la nouvelle architecture.
- Reconvertir vos personnalisations en variables CSS dans un bloc
@theme ou en CSS direct après les imports.
- Regénérer le fichier de thème avec la commande Filament pour bénéficier de la nouvelle structure compatible Tailwind v4.
- Vérifier vos sélecteurs CSS custom : certaines classes Filament ont pu changer entre v3 et v4.
La bonne nouvelle, c'est que l'approche CSS-first de Tailwind v4 simplifie la chaîne de build et rend les personnalisations plus lisibles et centralisées.
Conclusion
La transition vers Tailwind CSS v4 avec Filament v4/v5 implique un changement de paradigme dans la gestion des thèmes : exit tailwind.config.js, place à une configuration déclarative directement dans le CSS. Une fois ce principe intégré, la personnalisation de vos panels Filament devient plus directe et mieux alignée avec les standards modernes du CSS.
Pour les projets Laravel qui exploitent Filament comme socle d'administration, prendre le temps de comprendre cette nouvelle architecture de thèmes est un investissement qui facilite la maintenance à long terme.
