ColorSwatchField

Preset color picker: horizontal swatch pills with optional section header and tooltips.

← Back to Table of Contents

Summary

Preset color picker featuring horizontal swatch pills with optional section headers and hover tooltips. Ideal for theme selection, category coloring, or any case where users choose from a predefined palette.

Class	Bjanczak\FilamentFlexFields\Filament\Forms\Components\ColorSwatchField
State type	string|null — selected color key (not hex)
FieldType	color_presets
Playground	color-swatch slug in Flex Fields playground

---

Basic usage

Standard Theme Colors

use Bjanczak\FilamentFlexFields\Filament\Forms\Components\ColorSwatchField;

ColorSwatchField::make('theme_color')
    ->colors([
        'indigo' => '#6366f1',
        'rose' => '#f43f5e',
        'emerald' => '#10b981',
    ])
    ->sectionLabel('Brand colors')
    ->tooltips(true);

Large Swatches with Custom Tooltips

ColorSwatchField::make('accent')
    ->colors(['primary' => '#3b82f6', 'white' => '#ffffff'])
    ->tooltips([
        'primary' => 'Primary Brand Blue',
        'white' => 'Pure White',
    ])
    ->size('lg');

---

State & validation

Stored value

State is the array key from colors(), not the hex value. This allows you to change the hex values in your code without breaking existing database records.

$record->theme_color; // 'indigo'

Validation rules (built-in)

Rule	Detail
nullable	No selection allowed (unless required())
string	Rejects arrays, objects and numeric payloads
Rule::in(...)	Key must exist in the configured colors() array

---

Configuration API

All methods accept Closure unless noted.

Method	Type	Default	Description
colors(array|Closure $colors)	Setup	[]	Map of key => hex (or CSS color)
sectionLabel(string|Closure|null $label)	Setup	null	Heading above swatches
sectionIcon(string|BackedEnum|Htmlable|Closure|null $icon)	Setup	config	Icon next to section label
tooltips(bool|array|Closure $tooltips)	Setup	false	true for auto-labels, or custom array
size(string $size)	Setup	'md'	sm, md, lg

---

Real-world examples

Status Color Picker

ColorSwatchField::make('status_color')
    ->colors([
        'danger' => '#ef4444',
        'warning' => '#f59e0b',
        'success' => '#10b981',
        'info' => '#3b82f6',
    ])
    ->tooltips(true)
    ->required();

Compact Palette

ColorSwatchField::make('tag_color')
    ->colors($this->getAvailableColors())
    ->size('sm')
    ->hiddenLabel();

---

Interaction, contrast and lifecycle

Tooltip labels use compact 4px vertical and 8px horizontal padding.

White and black swatches keep a visible edge in both themes. The selected ring uses an independent contrasting color, so selection remains visible even when the swatch matches the page background. The initial selection, radio semantics and tab stop are rendered by PHP; there is no introductory selection animation on reload.

• Tab enters the group once, at the selected option (or the first option).
• Arrow keys select and focus the next or previous color, wrapping at the ends.
• RTL reverses horizontal arrows. Home and End select the first and last option.
• Space and Enter activate the focused swatch through its native button.
• disabled() renders disabled buttons and prevents changes. required() rejects an empty value.
• Reduced motion disables selection and hover transitions.

Each rendered field owns its stylesheet and small JS entry through the FLEX asset runtime. It has no global listeners, timers, polling or network requests for colors. Dynamic palettes and labels are evaluated on the server. Removed keys must be replaced or cleared in your application; they fail validation if submitted.

Palette values accept CSS colors, including hex, named colors, RGB/HSL and CSS variables. Empty keys/colors and CSS declaration delimiters are rejected. A palette is developer configuration, not arbitrary CSS from submitted form data.

ColorSwatchField::make('accent')
    ->colors(fn (): array => ['white' => '#fff', 'black' => '#000'])
    ->tooltips(['white' => __('White'), 'black' => __('Black')])
    ->default('white')
    ->required();

ColorSwatchField::make('locked_accent')
    ->colors(['white' => '#fff', 'black' => '#000'])
    ->default('black')
    ->disabled();

Playground

/admin/flex-fields/color-swatch

See Playground for setup.

---

Related components

Component	When to use instead
FlexColorPickerField	Full HSV/Grid color picker for any color
ChoiceCards	Large card-style selection
NpsField	Survey-style color-coded scales

---

CSS classes (reference)

Class	Role
fff-color-swatch	Root wrapper
fff-color-swatch--{sm|md|lg}	Size variant
fff-color-swatch__header	Section label container
fff-color-swatch__pills	Swatch pills container
fff-color-swatch__pill	Individual color button
is-selected	Selected state
is-disabled	Disabled state