Advanced Custom Fields: Color Picker Field GitLab

Adds a Predefined Color Picker field type to Advanced Custom Fields (ACF or ACF PRO 6.0+).

Where ACF's own Color Picker hands the editor a free colour wheel, this one starts from a palette the field group defines. Editors pick approved brand colours; the free picker is opt-in per field for the cases that genuinely need it.

It appears under Custom Field Types in the field type list, so it never gets confused with core's Color Picker.

Requirements

No build step. No dependencies beyond ACF and the wp-color-picker script that ships with WordPress.

Installation

1. Copy the acf-color-picker-field folder into wp-content/plugins/.
2. Activate ACF (or ACF PRO), then this plugin.
3. Add a Predefined Color Picker field to a field group and fill in Palette.

Defining the palette

One colour per line. A label after a spaced colon is optional and becomes the swatch tooltip, its accessible name, and the caption when Show Labels is on.

#E53935 : Brand Red
#1E88E5 : Brand Blue
rgba(0,0,0,0.5) : Overlay
#43A047

Accepted notations, all normalised to one canonical form before they are stored or rendered:

Anything else — named colours, hsl(), var(), url(), stray CSS — is dropped from the palette and rejected on save.

Settings

General

Validation

Presentation

Using the value

Default return format gives the colour string, ready for an inline style or a custom property:

<div class="card" style="--accent: <?php echo esc_attr( get_field( 'accent' ) ); ?>">

The array format adds the palette label and the RGBA components:

$accent = get_field( 'accent' );

// array(
//     'value' => '#e53935',
//     'label' => 'Brand Red',
//     'red'   => 229,
//     'green' => 57,
//     'blue'  => 53,
//     'alpha' => 1.0,
// )

An empty value returns '' in both formats, so if ( $accent ) behaves as expected.

Filters

palette_color_picker_args (JS) — options passed to wpColorPicker for the custom-colour picker:

acf.addFilter( 'palette_color_picker_args', function ( args ) {
    args.palettes = true;
    return args;
} );

acf/localized_field_categories (PHP) — the plugin registers the custom category label as "Custom Field Types", but only when nothing has claimed it yet. Any other plugin that sets category = 'custom' on its field type joins the same group; the first label registered wins.

Notes on the implementation

The palette is enforced server side. update_value() re-checks the palette independently of validate_value(), because ACF skips field validation on drafts and autosaves. A colour outside the palette is discarded unless a custom colour is allowed, and a value that is not a valid colour is always discarded — so nothing unvalidated reaches a style attribute or the database.

Built on real radio inputs under role="radiogroup", extending ACF's own radio field type in JS. Arrow-key navigation, focus rings, screen-reader labels and the allow_null click-to-deselect behaviour come from the platform and from ACF rather than from custom scripting. The picker's text input deliberately carries no name: the custom radio is the only control that submits.

Contrast is computed per swatch. The check mark's ink is chosen from the colour's perceived brightness, composited over the white field background, so it stays legible on #FFFFFF and #000000 alike. Translucent palette entries render over a checkerboard.

Where it works: repeaters, flexible content, groups, side meta boxes, the block editor sidebar, term and user forms, and acf_form() on the front end. The swatch row wraps to whatever width it is given. Conditional logic supports "has any value", "has no value", "is equal to" and "is not equal to".

Internal type name is palette_color_picker, so there is no clash with core's color_picker in get_field_object(), field group JSON, or acf_get_field_type().

Layout

acf-color-picker-field.php   Bootstrap: version, ACF guard, category label
src/Field.php                The field type
assets/css/input.css         Swatch UI
assets/js/input.js           Radio extension + wp-color-picker wiring
assets/images/               Field type preview

License

GPLv2 or later.