Introduction
Filament uses CSS variables to define its color palette. These CSS variables are mapped to Tailwind classes in the preset file that you load when installing Filament. The reason why Filament uses CSS variables is that it allows the framework to pass a color palette from PHP via a <style> element that gets rendered as part of the @filamentStyles Blade directive.
By default, Filament’s Tailwind preset file ships with 6 colors:
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
When you assign a color to a Filament component (for example ->color('primary')), Filament receives the entire 11-shade palette and decides at runtime which shade to use for the background, text, hover state, dark-mode variants, and so on. The selection is driven by WCAG 2.1 contrast ratios: for each slot, Filament walks the palette and picks the lightest (or darkest, depending on context) shade that meets the minimum contrast against the surface the component sits on.
This design means:
- You only need to register one palette per color name. Per-component shade selection is automatic.
- The same color can render differently across components — a
success button uses one bg/text combination, a success badge another — because each component applies contrast rules suited to its visual role.
- If you swap a palette out (for example, switching
primary from amber to a darker hue), every component that uses it re-derives its shades to stay accessible.
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.
Why some buttons render dark text instead of white
For solid buttons, Filament builds a “best text shade per background shade” lookup up-front, then picks the actual button background by checking which candidate background shades end up paired with light text.
For vibrant colors like red, blue, or indigo, shade 600 is dark enough that white text passes the 4.5:1 contrast threshold. The resolver picks bg: 600, hover:bg: 500, with white text — the path most colors take.
For pale colors like yellow, amber, or lime, even shade 600 is bright enough that dark text passes contrast better than white. The resolver detects this and falls back to a paler background — bg: 400 — paired with dark text. The result is a yellow button with dark text on a light-yellow background, instead of an unreadable white-on-yellow combination.
This behavior is intentional. Forcing every color into the same bg: 600, text: white pattern would produce inaccessible combinations for warm or pale palettes. The two-path design keeps success and danger looking like solid coloured buttons while warning (typically amber) reads correctly with its lighter background.
Customizing shade selection
If you need to override how a particular component picks its shades — for example, to enforce WCAG AAA contrast across the app, or to bias buttons toward darker shades — 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() share the same shape (bg, hover, alternateHover?) and the same selection algorithm — they differ only in which mode they configure. Each call appends a candidate to the list for that mode, evaluated in order using two passes:
- Preferred — walk the list and stop at the first candidate whose
bg produces light text. For that candidate, use hover if it also produces light text; otherwise use alternateHover if it produces light text; otherwise skip.
- Fallback — if nothing qualified in pass 1, take the last candidate. Hover is
hover when its text-lightness is consistent with bg’s, otherwise alternateHover. The consistency check avoids a text-color flicker on hover.
alternateHover is treated identically on any candidate — first, last, or middle. It’s only consulted when the main hover isn’t appropriate.
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. Hover variants are derived from the resting shade by a fixed 100-shade offset that intensifies the icon. 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 enforces WCAG AAA contrast on solid buttons and biases the background choice toward darker shades:
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.
