Gradient Picker Field

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

php

[
    '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 gradient string, or the default value if nothing has been saved yet.

php

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

---

Usage Examples

Hero section background

php

$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

php

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

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

css

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

Section overlay gradient

php

[
    '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%)',
]

php

$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

php

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

php

$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

php

[
    '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 escape with esc_attr() before outputting in an inline style attribute.
• For a single solid color control, use the Color Picker field instead.