Introduction
You can configure Filament’s color palettes in PHP and use their names in PHP or Blade components. Filament selects shades from each palette for light and dark mode.
Filament provides 6 colors by default:
You can learn how to change these colors and register new ones.
How to pass a color to Filament
A registered “color” in Filament is not just one shade. In fact, it is an entire color palette made of 11 shades: 50, 100, 200, 300, 400, 500, 600, 700, 800, 900, and 950. When you use a color in Filament, the framework will decide which shade to use based on the context. For example, it might use the 600 shade for a component’s background, 500 when it is hovered, and 400 for its border. If the user has dark mode enabled, it might use 700, 800, or 900 instead.
On one hand, this means that you can specify a color in Filament without having to worry about the exact shade to use, or to specify a shade for each part of the component. Filament takes care of selecting a shade that should create an accessible contrast with other elements where possible.
To customize the color that something is in Filament, you can use its name. For example, if you wanted to use the success color, you could pass it to a color method of a PHP component like so:
If you would like to use a color in a Blade component, you can pass it as an attribute:
Customizing the default colors
From a service provider’s boot() method, or middleware, you can call the FilamentColor::register() method, which you can use to customize which colors Filament uses for UI elements.
There are 6 default colors that are used throughout Filament that you are able to customize:
The Color class contains every Tailwind CSS color to choose from.
You can also pass in a function to register() which will only get called when the app is getting rendered. This is useful if you are calling register() from a service provider, and want to access objects like the currently authenticated user, which are initialized later in middleware.
You may register a new color to use in any Filament component by passing it to the FilamentColor::register() method, with its name as the key in the array:
You will now be able to use secondary as a color in any Filament component.
Using a non-Tailwind color
You can use custom colors that are not included in the Tailwind CSS color palette by passing an array of color shades from 50 to 950 in OKLCH format:
Generating a custom color palette
If you want us to attempt to generate a palette for you based on a singular hex or RGB value, you can pass that in:
How Filament selects accessible shades
Filament selects shades using WCAG 2.1 contrast ratios. The same palette can produce different shades in a button, badge, or link because each component has different backgrounds and contrast requirements. Changing a registered palette updates these choices automatically.
The contrast thresholds Filament uses come from WCAG 2.1:
The Filament\Support\Colors\Color class exposes these as constants — WCAG_AA_TEXT, WCAG_AA_LARGE_TEXT, WCAG_AA_NON_TEXT, WCAG_AAA_TEXT, WCAG_AAA_LARGE_TEXT — so you can reference them by name when customizing.
Shade selection uses fallback shades when a palette cannot meet the requested contrast. It does not guarantee accessibility for every custom palette or background. Check contrast in light and dark mode, including hover states, after customizing colors or component styles.
Why some buttons render dark text instead of white
Solid buttons prefer backgrounds that support light text. Pale palettes such as yellow, amber, or lime may instead use a lighter background with dark text to preserve contrast. Avoid overriding these buttons to always use white text without checking the resulting contrast.
Customizing shade selection
If you need to override how a particular component picks its shades — for example, to target WCAG AAA contrast or prefer darker button backgrounds — you can extend the relevant view component and rebind it through Laravel’s container.
Filament exposes three color-map classes for this purpose, all under the Filament\Support\View\Components\ColorMaps namespace. Each follows the same fluent shape — make($palette) to start, chained configuration setters, then get() to return an array<string, int> mapping slot names (such as bg, text, dark:hover:bg) to shade numbers.
The three classes are:
ComponentColorMap — for components that pick one shade per slot, like badges, links, text columns, icons, dropdowns, and toggles.ButtonComponentColorMap — for solid buttons. Picks a background shade and pairs it with a matching text shade.IconButtonComponentColorMap — for icon-only buttons. Picks a single icon shade and derives a hover variant from it.
Components you can override
Every Filament component that picks shades from a palette implements getColorMap(). To customize one, extend the class, override getColorMap(), and bind your subclass through Laravel’s container.
The fastest way to write a custom getColorMap() is to copy the original implementation from the class you’re overriding and tweak the configuration values. The source files live alongside the documented classes in packages/<package>/src/View/Components/. Each one is a few lines of fluent calls — the easiest way to learn the surface is to read the default and change it.
ComponentColorMap
Builds a slot map one entry at a time. Call slot() once per output slot, then get().
slot() parameters:
$name — Output map key (text, bg, hover:text, dark:hover:bg, etc.).$surface — The color the chosen shade must contrast against (typically $gray[50], $gray[700], or 'oklch(1 0 0)').$minRatio — Minimum WCAG contrast ratio. Defaults to Color::WCAG_AA_TEXT (4.5); use WCAG_AA_NON_TEXT (3.0) for icons or WCAG_AAA_TEXT (7.0) for AAA.$maxShade — Optional upper bound on the shade number considered.$minShade — Optional lower bound.$shouldStartFromDarkest — Walk darkest→lightest instead of the default lightest→darkest. Use for dark-mode lookups.$fallback — Shade returned when no candidate qualifies. Typically 900 for light mode, 200 for dark mode.
Returns all eight slots a solid button needs (bg, hover:bg, dark:bg, dark:hover:bg, text, hover:text, dark:text, dark:hover:text) from one get() call. You configure which background shades to use; the matching text shade for each is found automatically. At least one lightBackground() and one darkBackground() are required.
minContrastRatio() sets the minimum WCAG ratio between bg and text. Defaults to Color::WCAG_AA_TEXT (4.5); set to WCAG_AAA_TEXT (7.0) for AAA.
lightBackground() and darkBackground() accept (bg, hover, alternateHover?). Chain candidates in preference order. Filament prefers candidates that support light text in both resting and hover states, using alternateHover when the main hover shade is unsuitable. The final candidate is the fallback. Provide a pale-friendly fallback to support palettes that need dark text.
To express a color-aware cascade — “use 800 if the palette can carry it, otherwise 700, otherwise 600, falling back to a paler bg with dark text for yellows” — chain candidates and end with a pale-friendly fallback:
The last candidate doubles as the fallback when no candidate produces light text on its bg. If you configure only vibrant-friendly candidates and your palette is pale, that last candidate is used anyway — likely producing a dark-text-on-dark-bg button. Always end with a pale-friendly candidate (typically bg around 400) to handle yellows, ambers, and limes.
text, hover:text, dark:text, dark:hover:text) for icon-only buttons. At least one lightSurface() and one darkSurface() are required.
minContrastRatio() — Minimum contrast ratio between icon and surface. Defaults to Color::WCAG_AA_NON_TEXT (3.0).lightSurface() / darkSurface() — The body surface color the icon must contrast against in each mode. Typically $gray[50] and $gray[700].darkMaxShade() — Upper bound on the shade considered for dark-mode icon color. Defaults to 500; lower for lighter icons.
Here is a complete subclass that targets WCAG AAA contrast and prefers darker button backgrounds. Verify the rendered contrast with your palettes and backgrounds, since fallback shades may not meet the target:
Bind your subclass in a service provider’s register() method:
The same pattern works for any of the components listed above — extend, override getColorMap(), and bind.
The defaults work for the overwhelming majority of palettes. Only override these classes if you have specific accessibility requirements (such as AAA compliance) or a design system that mandates different shade preferences.
