Filament allows customization of its user interface through the creation of custom stylesheets known as "themes." These themes replace the default CSS used by Filament and are based primarily on Tailwind CSS along with several plugins such as Tailwind Forms, Tailwind Typography, the PostCSS Nesting plugin, and Autoprefixer. The process to create and apply a custom stylesheet for Filament involves several steps including theme creation, editing the theme files, compiling the CSS, and registering the theme in the Filament panel.
Creating a Custom Theme
To create a custom theme, you use a built-in Artisan command:
php artisan make:filament-theme
If your application contains multiple Filament panels, you can specify which panel the theme is for:
php artisan make:filament-theme admin
Running this command generates a CSS file along with a Tailwind configuration file inside the `resources/css/filament` directory. This sets up a baseline where you can begin defining your custom styles. The command also provides instructions and output messages guiding you on compiling your custom stylesheet and registering it within the Filament panel setup.
Tailwind CSS Version and Compilation
Filament currently uses Tailwind CSS version 3. If Tailwind CSS v4 is installed in your project, it might not fully support or configure the necessary tooling to compile the theme correctly. It's recommended to use Tailwind CLI for compilation or align your Tailwind version with v3 for smooth theme compilation. Filament version 4 plans support for Tailwind CSS v4.After generating your theme files, the command output will also provide you the exact command to compile the CSS. This is typically done through the Tailwind CLI or other JavaScript package manager scripts. It's a common practice to save this compilation command as a script in your `package.json` for easier usage in development and production builds.
Editing the Theme CSS
Within the directory `resources/css/filament/`, the main theme CSS file can be customized. This CSS file generally imports the default Filament theme styles to preserve base styles and then applies customizations over them. For example, to customize the sidebar's background and text colors, you can use Tailwind's utility classes and Filament-specific class names prefixed with `.fi-` such as `.fi-sidebar`, `.fi-sidebar-header`, `.fi-icon-btn-icon`, `.fi-sidebar-item-button`, etc.You can apply Tailwind utility classes with `@apply` directive to these classes to change colors, spacings, and other styles. For example:
css
@import '/vendor/filament/filament/resources/css/theme.css';
.fi-sidebar {
@apply bg-gray-500;
}
.fi-sidebar-header .fi-icon-btn-icon {
@apply text-primary-500;
}
.fi-sidebar-item-active .fi-sidebar-item-button {
@apply bg-primary-500;
}
.fi-sidebar-item-button:hover {
@apply hover:bg-primary-500;
}
This approach uses Tailwind's utility-first CSS methodology to override and extend the default visual design. You can customize fonts, colors, spacing, borders, shadows, and virtually any CSS feature available through Tailwind.
Tailwind Plugins and Configuration
The theme depends on several Tailwind plugins:- `@tailwindcss/forms` for styling form elements.
- `@tailwindcss/typography` for rich text styling.
- PostCSS Nesting plugin to allow nested CSS rules similar to SCSS.
- Autoprefixer for ensuring cross-browser compatibility.
You need to install these as development dependencies via npm:
npm install tailwindcss @tailwindcss/forms @tailwindcss/typography autoprefixer tippy.js --save-dev
The `tailwind.config.js` file should include the necessary plugins and extend the theme with custom colors or other design tokens if needed. For example:
js
import colors from 'tailwindcss/colors';
import forms from '@tailwindcss/forms';
import typography from '@tailwindcss/typography';
export default {
content: [
'./resources/**/*.blade.php',
'./vendor/filament/**/*.blade.php',
],
darkMode: 'class',
theme: {
extend: {
colors: {
danger: colors.rose,
primary: colors.blue,
success: colors.green,
warning: colors.yellow,
},
},
},
plugins: [
forms,
typography,
],
};
Registering and Using the Theme
After creating and customizing your theme CSS, you have to register it in the Filament panel provider in your Laravel application. This is typically done in the `PanelServiceProvider` or wherever the panel is configured. You add the theme by specifying the path to the compiled CSS via the `viteTheme` method on the panel instance:php
use Filament\Panel;
public function panel(Panel $panel): Panel
{
return $panel
// other panel configurations...
->viteTheme('resources/css/filament/admin/theme.css');
}
Make sure the path matches the compiled CSS file location after running the build process.
Compiling the Theme
Compile your custom theme using the command output by the `make:filament-theme` Artisan command. Usually, this is done by running:
npm run build
or a custom command that calls Tailwind CSS with the right input and output files. This process converts your Tailwind CSS, nested rules, and other directives into a fully processed CSS file that Filament can use.
Customizing UI Components
Filament uses specific CSS classes prefixed with `.fi-` for different UI parts such as sidebar, navigation items, buttons, forms, dashboard widgets, and more. To customize these components:- Use the `.fi-sidebar` series of classes to control the sidebar styles.
- Modify `.fi-sidebar-item`, `.fi-sidebar-item-active`, `.fi-icon-btn` for navigation items and icons.
- For forms, style inputs and labels by targeting `.fi-form-input`, `.fi-form-label`, and similar form classes.
- Customize dashboard widgets by targeting their wrapper classes and applying Tailwind utilities for color, padding, margins, and shadows.
It's recommended to explore the existing classes provided by Filament, which can be found in the default theme CSS file, to understand the structure. Then override or extend styles in your custom theme.
Advanced Customization Tips
- Use Render Hooks: Filament provides render hooks that allow injecting custom HTML or UI elements at specific places in the UI. Combined with custom styles, you can create unique interfaces.- Divide Forms into Sections: Customize form layouts by dividing forms into sections, columns, or grid layouts using Tailwind CSS grid and flex utilities.
- Use Tailwind Variants and Responsiveness: Apply responsive design principles by using Tailwind's responsive prefixes like `sm:`, `md:`, `lg:` to customize the Filament UI across devices.
- Dark Mode: Enable and configure dark mode by using Tailwind's dark variant utilities and managing the `darkMode` property in `tailwind.config.js`.
Summary of Steps to Create a Custom Filament UI Stylesheet
1. Run the command to generate a theme base:
php artisan make:filament-theme [panel-name]
2. Install Tailwind CSS and the necessary plugins if not installed.
3. Edit the generated CSS file in `resources/css/filament` to add your custom styles, utilizing Tailwind CSS utility classes and Filament `.fi-` prefixed classes.
4. Update or create `tailwind.config.js`, ensuring plugins are registered and content paths include your views and vendor Blade files.
5. Register the compiled CSS in your Filament panel provider using `viteTheme()`.
6. Compile your theme CSS using the Tailwind CLI or npm script:
npm run build
7. Use render hooks and component classes for further customization of the UI interface.
8. Test the interface, iterate on styles, and recompile as needed for customization refinement. Filament's theming system, built on Tailwind CSS, offers a flexible and straightforward approach to extensively customize the UI, from colors and typography to complex layouts and component styling. By leveraging Laravel's Artisan tools and the Tailwind ecosystem, developers can craft unique and branded admin panel experiences tailored to their applications' needs.