Gradient Picker Field

A gradient builder for creating linear or radial CSS gradients.

Last updated: June 14, 2026

Overview

The Gradient Picker field renders a visual gradient builder with color stop controls, angle input, and linear/radial mode selection. It returns a complete CSS gradient() string ready to use directly in a background or background-image property. Use it for hero backgrounds, section overlays, button gradients, or any other element that needs a multi-color gradient.

Field Registration

[
    'id'      => 'hero_gradient',
    'type'    => 'gradient_picker',
    'title'   => __('Hero Background Gradient', 'your-textdomain'),
    'subtitle' => __('Applied to the hero section background', 'your-textdomain'),
    'default' => 'linear-gradient(135deg, #2271b1 0%, #00a32a 100%)',
]

Field Options

Option	Type	Required	Description
`id`	`string`	✅	Unique field identifier — used as the option key
`type`	`string`	✅	Must be `gradient_picker`
`title`	`string`	✅	Label shown above the field
`subtitle`	`string`	—	Smaller descriptive text shown below the label
`desc`	`string`	—	Help text shown below the gradient picker
`default`	`string`	—	Default gradient as a valid CSS gradient string
`required`	`array`	—	Conditional logic rules — see Conditional Logic

Return Value

Type: string

Returns a complete CSS linear-gradient() string ready to use directly in a background or background-image property. Returns the default value if nothing has been saved yet. Returns an empty string '' if the field was cleared.

$gradient = themeplus_get_option( 'hero_gradient', '' );
// Returns: 'linear-gradient(135deg, #2271b1 0%, #00a32a 100%)'
// Returns: '' when cleared or nothing saved and no default set

Usage Examples

Hero section background

$gradient = themeplus_get_option( 'hero_gradient', 'linear-gradient(135deg, #2271b1 0%, #00a32a 100%)' );

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

CSS custom property

$gradient = themeplus_get_option( 'hero_gradient', 'linear-gradient(135deg, #2271b1 0%, #00a32a 100%)' );

echo '<style>
    :root {
        --hero-gradient: ' . esc_attr( $gradient ) . ';
    }
</style>';

.hero {
    background-image: var(--hero-gradient);
}

Section overlay gradient

[
    'id'      => 'section_overlay',
    'type'    => 'gradient_picker',
    'title'   => __('Section Overlay', 'your-textdomain'),
    'subtitle' => __('Gradient overlay applied on top of section background images', 'your-textdomain'),
    'default' => 'linear-gradient(180deg, rgba(0,0,0,0) 0%, rgba(0,0,0,0.7) 100%)',
]

$overlay = themeplus_get_option( 'section_overlay', 'linear-gradient(180deg, rgba(0,0,0,0) 0%, rgba(0,0,0,0.7) 100%)' );

echo '<div class="section-overlay" style="background-image: ' . esc_attr( $overlay ) . ';"></div>';

Button gradient background

[
    'id'      => 'button_gradient',
    'type'    => 'gradient_picker',
    'title'   => __('Button Gradient', 'your-textdomain'),
    'default' => 'linear-gradient(90deg, #2271b1 0%, #00a32a 100%)',
]

$btn_gradient = themeplus_get_option( 'button_gradient', 'linear-gradient(90deg, #2271b1 0%, #00a32a 100%)' );

echo '<style>
    .btn-primary {
        background-image: ' . esc_attr( $btn_gradient ) . ';
    }
</style>';

With a conditional field

[
    'id'      => 'hero_bg_type',
    'type'    => 'button_set',
    'title'   => __('Hero Background Type', 'your-textdomain'),
    'default' => 'color',
    'options' => [
        'color'    => __('Solid Color', 'your-textdomain'),
        'gradient' => __('Gradient', 'your-textdomain'),
        'image'    => __('Image', 'your-textdomain'),
    ],
],
[
    'id'       => 'hero_bg_color',
    'type'     => 'color',
    'title'    => __('Hero Background Color', 'your-textdomain'),
    'default'  => '#2271b1',
    'required' => ['hero_bg_type', '==', 'color'],
],
[
    'id'       => 'hero_bg_gradient',
    'type'     => 'gradient_picker',
    'title'    => __('Hero Background Gradient', 'your-textdomain'),
    'default'  => 'linear-gradient(135deg, #2271b1 0%, #00a32a 100%)',
    'required' => ['hero_bg_type', '==', 'gradient'],
],
[
    'id'       => 'hero_bg_image',
    'type'     => 'image',
    'title'    => __('Hero Background Image', 'your-textdomain'),
    'required' => ['hero_bg_type', '==', 'image'],
],

Notes

The field returns a complete CSS gradient string — use it directly in background-image or as a CSS custom property value. Do not wrap it in url().
Always check that the returned value is non-empty before using it — if the field was cleared by the user and no default is set, it returns an empty string. Use if ( $gradient ) before outputting.
Always escape with esc_attr() before outputting in an inline style attribute.
For a single solid color control, use the Color Picker field instead.

Quick Links