Color Picker Field

A color picker for selecting a single color value.

Overview

The Color Picker field renders a color swatch button that opens a full color picker panel with hex, RGB, and HSL input modes, an opacity/alpha slider, and a saved colors palette. It returns the selected color as a hex or rgba string. Use it for primary and secondary brand colors, background colors, text colors, border colors, or any other single color option in your theme.

For a two-stop gradient control, use the Gradient Picker field.

Field Registration

[
    'id'       => 'primary_color',
    'type'     => 'color',
    'title'    => __( 'Primary Color', 'your-textdomain' ),
    'subtitle' => __( 'Main brand color used throughout the theme', 'your-textdomain' ),
    'default'  => '#2271b1',
]

Field Options

Option	Type	Required	Description
id	string	✅	Unique field identifier — used as the option key
type	string	✅	Must be color
title	string	✅	Label shown above the field
subtitle	string	—	Descriptive text shown below the label
desc	string	—	Alternative to subtitle — shown in the same position
default	string	—	Default color — hex (e.g. '#2271b1') or rgba (e.g. 'rgba(34,113,177,0.8)'). Default: '#000000'
required	array	—	Conditional logic rules — see Conditional Logic

Return Value

Type: string

Returns the selected color as a hex string when fully opaque, or an rgba string when the user sets opacity below 100%. Returns the default value if nothing has been saved yet.

$color = themeplus_get_option( 'primary_color', '#2271b1' );
// Returns: '#2271b1'           (fully opaque — hex)
// Returns: 'rgba(34,113,177,0.8)'  (with opacity — rgba)

Usage Examples

CSS custom property

$primary   = themeplus_get_option( 'primary_color', '#2271b1' );
$secondary = themeplus_get_option( 'secondary_color', '#646970' );
$accent    = themeplus_get_option( 'accent_color', '#00a32a' );

echo '<style>
    :root {
        --color-primary:   ' . esc_attr( $primary )   . ';
        --color-secondary: ' . esc_attr( $secondary ) . ';
        --color-accent:    ' . esc_attr( $accent )    . ';
    }
</style>';

Inline background color

$hero_bg = themeplus_get_option( 'hero_bg_color', '#000000' );

echo '<section class="hero" style="background-color: ' . esc_attr( $hero_bg ) . ';">';

Getting all colors at once — recommended for multiple fields

$options = themeplus_get_option();

$colors = [
    '--color-primary'   => $options['primary_color']   ?? '#2271b1',
    '--color-secondary' => $options['secondary_color'] ?? '#646970',
    '--color-accent'    => $options['accent_color']    ?? '#00a32a',
    '--color-text'      => $options['text_color']      ?? '#1e1e1e',
    '--color-bg'        => $options['bg_color']        ?? '#ffffff',
];

echo '<style>:root{';
foreach ( $colors as $property => $value ) {
    echo esc_attr( $property ) . ':' . esc_attr( $value ) . ';';
}
echo '}</style>';

With a conditional field

[
    'id'      => 'header_style',
    'type'    => 'button_set',
    'title'   => __( 'Header Style', 'your-textdomain' ),
    'default' => 'light',
    'options' => [
        'light'       => __( 'Light', 'your-textdomain' ),
        'dark'        => __( 'Dark', 'your-textdomain' ),
        'transparent' => __( 'Transparent', 'your-textdomain' ),
        'custom'      => __( 'Custom Color', 'your-textdomain' ),
    ],
],
[
    'id'       => 'header_custom_bg',
    'type'     => 'color',
    'title'    => __( 'Header Background Color', 'your-textdomain' ),
    'default'  => '#ffffff',
    'required' => ['header_style', '==', 'custom'],
],

Notes

• Always escape color values with esc_attr() before outputting in HTML attributes or inline styles.
• The field returns either a hex string (#rrggbb) or an rgba string (rgba(r,g,b,a)) — always handle both formats. The safest approach is to pass the value directly to a CSS custom property and let the browser handle both.
• The default value falls back to '#000000' if you do not set one — always provide a meaningful default that matches your theme’s color scheme.
• For a two-stop gradient, use the Gradient Picker field. For a full background control with color, image, and gradient modes, use the Background field.