> ## Documentation Index > Fetch the complete documentation index at: https://filament-34a8cf01.mintlify.site/llms.txt > Use this file to discover all available pages before exploring further. # Colors > [!WARNING] > > You are currently viewing the documentation for Filament 4.x, which is a previous version of Filament. > > Looking for the current stable version? Visit the [5.x documentation](https://filament-34a8cf01.mintlify.site/5.x/styling/colors.md). ## 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: * `primary`, which is [Tailwind's `amber` color](https://tailwindcss.com/docs/customizing-colors) by default * `success`, which is [Tailwind's `green` color](https://tailwindcss.com/docs/customizing-colors) by default * `warning`, which is [Tailwind's `amber` color](https://tailwindcss.com/docs/customizing-colors) by default * `danger`, which is [Tailwind's `red` color](https://tailwindcss.com/docs/customizing-colors) by default * `info`, which is [Tailwind's `blue` color](https://tailwindcss.com/docs/customizing-colors) by default * `gray`, which is [Tailwind's `zinc` color](https://tailwindcss.com/docs/customizing-colors) by default You can [learn how to change these colors and register new ones](#customizing-the-default-colors). ## 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](https://tailwindcss.com/docs/customizing-colors): `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: ```php theme={"theme":"gruvbox-dark-hard"} use Filament\Actions\Action; use Filament\Forms\Components\Toggle; Action::make('proceed') ->color('success') Toggle::make('is_active') ->onColor('success') ``` If you would like to use a color in a [Blade component](../components), you can pass it as an attribute: ```blade theme={"theme":"gruvbox-dark-hard"} Active ``` ## 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: ```php theme={"theme":"gruvbox-dark-hard"} use Filament\Support\Colors\Color; use Filament\Support\Facades\FilamentColor; FilamentColor::register([ 'danger' => Color::Red, 'gray' => Color::Zinc, 'info' => Color::Blue, 'primary' => Color::Amber, 'success' => Color::Green, 'warning' => Color::Amber, ]); ``` The `Color` class contains every [Tailwind CSS color](https://tailwindcss.com/docs/customizing-colors#color-palette-reference) to choose from. Loading preview ![Panel with custom primary color](https://filament-34a8cf01.mintlify.site/docs/images/4.x/light/panels/configuration/colors.jpg) 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. ### Registering extra colors 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: ```php theme={"theme":"gruvbox-dark-hard"} use Filament\Support\Colors\Color; use Filament\Support\Facades\FilamentColor; FilamentColor::register([ 'secondary' => Color::Indigo, ]); ``` 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](https://tailwindcss.com/docs/customizing-colors#color-palette-reference) palette by passing an array of color shades from `50` to `950` in OKLCH format: ```php theme={"theme":"gruvbox-dark-hard"} use Filament\Support\Facades\FilamentColor; FilamentColor::register([ 'danger' => [ 50 => 'oklch(0.969 0.015 12.422)', 100 => 'oklch(0.941 0.03 12.58)', 200 => 'oklch(0.892 0.058 10.001)', 300 => 'oklch(0.81 0.117 11.638)', 400 => 'oklch(0.712 0.194 13.428)', 500 => 'oklch(0.645 0.246 16.439)', 600 => 'oklch(0.586 0.253 17.585)', 700 => 'oklch(0.514 0.222 16.935)', 800 => 'oklch(0.455 0.188 13.697)', 900 => 'oklch(0.41 0.159 10.272)', 950 => 'oklch(0.271 0.105 12.094)', ], ]); ``` ### 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: ```php theme={"theme":"gruvbox-dark-hard"} use Filament\Support\Facades\FilamentColor; FilamentColor::register([ 'danger' => '#ff0000', ]); FilamentColor::register([ 'danger' => 'rgb(255, 0, 0)', ]); ``` ## How Filament selects accessible shades Filament selects shades using [WCAG 2.1 contrast ratios](https://www.w3.org/WAI/WCAG21/Understanding/contrast-minimum.html). 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: * **Normal text (`Color::WCAG_AA_TEXT`, 4.5:1)** — applied to text-bearing components such as buttons, badges, links, dropdown items, and text columns. From [success criterion 1.4.3 Contrast (Minimum)](https://www.w3.org/WAI/WCAG21/Understanding/contrast-minimum.html). * **User interface components and graphical objects (`Color::WCAG_AA_NON_TEXT`, 3:1)** — applied to icon-only components such as icon buttons, toggles, icon columns, and icon entries. From [success criterion 1.4.11 Non-text Contrast](https://www.w3.org/WAI/WCAG21/Understanding/non-text-contrast.html). 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. > [!WARNING] > > 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` 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. | Component class | Used by | Documentation | | - | - | - | | `Filament\Support\View\Components\BadgeComponent` | Badges | [Badge](https://filament-34a8cf01.mintlify.site/4.x/components/badge.md) | | `Filament\Support\View\Components\ButtonComponent` | Buttons (solid and outlined) | [Button](https://filament-34a8cf01.mintlify.site/4.x/components/button.md) | | `Filament\Support\View\Components\IconButtonComponent` | Icon-only buttons | [Icon button](https://filament-34a8cf01.mintlify.site/4.x/components/icon-button.md) | | `Filament\Support\View\Components\LinkComponent` | Links | [Link](https://filament-34a8cf01.mintlify.site/4.x/components/link.md) | | `Filament\Support\View\Components\ToggleComponent` | Form toggle | [Toggle](https://filament-34a8cf01.mintlify.site/4.x/forms/toggle.md) | | `Filament\Support\View\Components\DropdownComponent\HeaderComponent` | Dropdown headers | [Dropdown](https://filament-34a8cf01.mintlify.site/4.x/components/dropdown.md) | | `Filament\Support\View\Components\DropdownComponent\ItemComponent` | Dropdown items | [Dropdown](https://filament-34a8cf01.mintlify.site/4.x/components/dropdown.md) | | `Filament\Schemas\View\Components\TextComponent` | Schema text primes | [Prime components](https://filament-34a8cf01.mintlify.site/4.x/schemas/primes.md) | | `Filament\Infolists\View\Components\TextEntryComponent\ItemComponent` | Infolist text entries | [Text entry](https://filament-34a8cf01.mintlify.site/4.x/infolists/text-entry.md) | | `Filament\Infolists\View\Components\IconEntryComponent\IconComponent` | Infolist icon entries | [Icon entry](https://filament-34a8cf01.mintlify.site/4.x/infolists/icon-entry.md) | | `Filament\Tables\View\Components\Columns\TextColumnComponent\ItemComponent` | Table text columns | [Text column](https://filament-34a8cf01.mintlify.site/4.x/tables/columns/text.md) | | `Filament\Tables\View\Components\Columns\IconColumnComponent\IconComponent` | Table icon columns | [Icon column](https://filament-34a8cf01.mintlify.site/4.x/tables/columns/icon.md) | | `Filament\Tables\View\Components\Columns\Summarizers\CountComponent\IconComponent` | Table count summarizers | [Summaries](https://filament-34a8cf01.mintlify.site/4.x/tables/summaries.md) | | `Filament\Widgets\View\Components\StatsOverviewWidgetComponent\StatComponent\DescriptionComponent` | Stats overview widget descriptions | [Stats overview](https://filament-34a8cf01.mintlify.site/4.x/widgets/stats-overview.md) | > [!TIP] > > 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//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()`. ```php theme={"theme":"gruvbox-dark-hard"} use Filament\Support\Colors\Color; use Filament\Support\Facades\FilamentColor; use Filament\Support\View\Components\ColorMaps\ComponentColorMap; $gray = FilamentColor::getColor('gray'); ComponentColorMap::make($color) ->slot('text', surface: $gray[50], minRatio: Color::WCAG_AA_TEXT, fallback: 900) ->slot('dark:text', surface: $gray[700], maxShade: 500, shouldStartFromDarkest: true, fallback: 200) ->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. ### `ButtonComponentColorMap` 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. ```php theme={"theme":"gruvbox-dark-hard"} use Filament\Support\Colors\Color; use Filament\Support\View\Components\ColorMaps\ButtonComponentColorMap; ButtonComponentColorMap::make($color) ->minContrastRatio(Color::WCAG_AA_TEXT) ->lightBackground(bg: 600, hover: 500) ->lightBackground(bg: 400, hover: 300, alternateHover: 500) ->darkBackground(bg: 600, hover: 500, alternateHover: 700) ->get(); ``` `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: ```php theme={"theme":"gruvbox-dark-hard"} ButtonComponentColorMap::make($color) ->lightBackground(bg: 800, hover: 700) ->lightBackground(bg: 700, hover: 600) ->lightBackground(bg: 600, hover: 500) ->lightBackground(bg: 400, hover: 300, alternateHover: 500) // pale fallback ->darkBackground(bg: 600, hover: 500, alternateHover: 700) ->get(); ``` > [!WARNING] > > 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. ### `IconButtonComponentColorMap` Returns the four icon slots (`text`, `hover:text`, `dark:text`, `dark:hover:text`) for icon-only buttons. At least one `lightSurface()` and one `darkSurface()` are required. ```php theme={"theme":"gruvbox-dark-hard"} use Filament\Support\Colors\Color; use Filament\Support\Facades\FilamentColor; use Filament\Support\View\Components\ColorMaps\IconButtonComponentColorMap; $gray = FilamentColor::getColor('gray'); IconButtonComponentColorMap::make($color) ->minContrastRatio(Color::WCAG_AA_NON_TEXT) ->lightSurface($gray[50]) ->darkSurface($gray[700]) ->darkMaxShade(500) ->get(); ``` * `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. ### Worked example: AAA contrast for buttons 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: ```php theme={"theme":"gruvbox-dark-hard"} namespace App\View\Components; use Filament\Support\Colors\Color; use Filament\Support\Facades\FilamentColor; use Filament\Support\View\Components\ButtonComponent as BaseButtonComponent; use Filament\Support\View\Components\ColorMaps\ButtonComponentColorMap; use Filament\Support\View\Components\ColorMaps\ComponentColorMap; class ButtonComponent extends BaseButtonComponent { public function getColorMap(array $color): array { $gray = FilamentColor::getColor('gray'); if ($this->isOutlined) { return ComponentColorMap::make($color) ->slot('text', surface: $gray[50], minRatio: Color::WCAG_AAA_TEXT, fallback: 900) ->slot('dark:text', surface: $gray[700], minRatio: Color::WCAG_AAA_TEXT, maxShade: 500, shouldStartFromDarkest: true, fallback: 200) ->get(); } return ButtonComponentColorMap::make($color) ->minContrastRatio(Color::WCAG_AAA_TEXT) ->lightBackground(bg: 700, hover: 600) ->lightBackground(bg: 400, hover: 300, alternateHover: 500) ->darkBackground(bg: 600, hover: 500, alternateHover: 700) ->get(); } } ``` Bind your subclass in a service provider's `register()` method: ```php theme={"theme":"gruvbox-dark-hard"} use App\View\Components\ButtonComponent; use Filament\Support\View\Components\ButtonComponent as BaseButtonComponent; public function register(): void { $this->app->bind(BaseButtonComponent::class, ButtonComponent::class); } ``` The same pattern works for any of the components listed above — extend, override `getColorMap()`, and bind. > [!TIP] > > 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. [Edit this page on GitHub](https://github.com/filamentphp/filament/edit/4.x/docs/08-styling/03-colors.md) ## Sponsored by [Your logo here](https://github.com/sponsors/danharrin) This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.