Background Field

Overview

The Background field renders a grouped control panel covering every aspect of a CSS background — color, image, position, size, repeat mode, and attachment. It returns an associative array of all selected values. Use it for section backgrounds, hero backgrounds, body backgrounds, or any other element that needs a full background definition in one setting.

---

Field Registration

php

[
    'id'       => 'hero_background',
    'type'     => 'background',
    'title'    => __( 'Hero Background', 'your-textdomain' ),
    'subtitle' => __( 'Background applied to the hero section', 'your-textdomain' ),
    // Mode flags — control which tabs appear in the UI
    'color'    => true,   // default: true  — color tab
    'image'    => false,  // default: false — image tab
    'gradient' => false,  // default: false — gradient tab
    'default'  => [
        'mode'       => 'color',
        'color'      => '#0a0a0a',
        'image'      => '',
        'position'   => 'center center',
        'size'       => 'cover',
        'repeat'     => 'no-repeat',
        'attachment' => 'scroll',
        'gradient'   => '',
    ],
]

---

Field Options

Option	Type	Required	Description
id	string	✅	Unique field identifier — used as the option key
type	string	✅	Must be background
title	string	✅	Label shown above the field
subtitle	string	—	Smaller descriptive text shown below the label
desc	string	—	Help text shown below the background controls
default	array	—	Default values — see sub-options below
required	array	—	Conditional logic rules — see Conditional Logic

Mode Flags

Flag	Type	Default	Description
color	bool	true	Show the color picker tab
image	bool	false	Show the image picker tab
gradient	bool	false	Show the gradient picker tab

Only color is enabled by default. Enable all three for a full background control:

'color'    => true,
'image'    => true,
'gradient' => true,

Default Sub-options

Key	Type	Description
mode	string	Active tab — 'color', 'image', or 'gradient'
color	string	Background color — hex or rgba string
image	string	Background image — full URL string, empty string when none
position	string	Background position — e.g. 'center center', 'top left'
size	string	Background size — 'cover', 'contain', or custom
repeat	string	Background repeat — 'no-repeat', 'repeat', 'repeat-x', 'repeat-y'
attachment	string	Background attachment — 'scroll' or 'fixed'
gradient	string	CSS gradient string — e.g. 'linear-gradient(135deg, #7F27FF, #17a2b8)'

Return Value

Type: array

Returns an associative array with 8 keys. Returns the default array if nothing has been saved yet.

php

$bg = themeplus_get_option( 'hero_background', [] );
// Returns:
// [
//     'mode'       => 'color',           // string — active mode: 'color', 'image', or 'gradient'
//     'color'      => '#0a0a0a',         // string — hex or rgba
//     'image'      => '',                // string — full URL (not an ID)
//     'position'   => 'center center',   // string
//     'size'       => 'cover',           // string
//     'repeat'     => 'no-repeat',       // string
//     'attachment' => 'scroll',          // string
//     'gradient'   => '',                // string — CSS gradient string
// ]

---

Usage Examples

Applying as inline CSS — mode-aware

php

$bg = themeplus_get_option( 'hero_background', [
    'mode'       => 'color',
    'color'      => '#0a0a0a',
    'image'      => '',
    'position'   => 'center center',
    'size'       => 'cover',
    'repeat'     => 'no-repeat',
    'attachment' => 'scroll',
    'gradient'   => '',
] );

$mode       = $bg['mode']       ?? 'color';
$color      = $bg['color']      ?? '#0a0a0a';
$image_url  = $bg['image']      ?? '';          // already a URL — use directly
$position   = $bg['position']   ?? 'center center';
$size       = $bg['size']       ?? 'cover';
$repeat     = $bg['repeat']     ?? 'no-repeat';
$attachment = $bg['attachment'] ?? 'scroll';
$gradient   = $bg['gradient']   ?? '';

$style = '';

if ( 'gradient' === $mode && $gradient ) {
    $style .= 'background: ' . esc_attr( $gradient ) . ';';
} elseif ( 'image' === $mode && $image_url ) {
    $style .= 'background-color: '        . esc_attr( $color )           . ';';
    $style .= 'background-image: url('    . esc_url( $image_url )        . ');';
    $style .= 'background-position: '     . esc_attr( $position )        . ';';
    $style .= 'background-size: '         . esc_attr( $size )            . ';';
    $style .= 'background-repeat: '       . esc_attr( $repeat )          . ';';
    $style .= 'background-attachment: '   . esc_attr( $attachment )      . ';';
} else {
    $style .= 'background-color: ' . esc_attr( $color ) . ';';
}

echo '<section class="hero" style="' . $style . '">';

CSS custom properties

php

$bg = themeplus_get_option( 'body_background', [] );

$mode       = $bg['mode']       ?? 'color';
$color      = $bg['color']      ?? '#ffffff';
$image_url  = $bg['image']      ?? '';
$position   = $bg['position']   ?? 'center center';
$size       = $bg['size']       ?? 'cover';
$repeat     = $bg['repeat']     ?? 'no-repeat';
$attachment = $bg['attachment'] ?? 'scroll';
$gradient   = $bg['gradient']   ?? '';

echo '<style>
    :root {
        --body-bg-color:      ' . esc_attr( $color )      . ';
        --body-bg-image:      ' . ( $image_url ? 'url(' . esc_url( $image_url ) . ')' : 'none' ) . ';
        --body-bg-position:   ' . esc_attr( $position )   . ';
        --body-bg-size:       ' . esc_attr( $size )       . ';
        --body-bg-repeat:     ' . esc_attr( $repeat )     . ';
        --body-bg-attachment: ' . esc_attr( $attachment ) . ';
        --body-bg-gradient:   ' . esc_attr( $gradient )   . ';
        --body-bg-mode:       ' . esc_attr( $mode )       . ';
    }
</style>';

Reusable helper function

php

function mytheme_get_background_style( string $option_id, array $defaults = [] ): string {
    $bg = themeplus_get_option( $option_id, $defaults );

    if ( empty( $bg ) ) {
        return '';
    }

    $mode       = $bg['mode']       ?? 'color';
    $color      = $bg['color']      ?? '';
    $image_url  = $bg['image']      ?? '';
    $position   = $bg['position']   ?? 'center center';
    $size       = $bg['size']       ?? 'cover';
    $repeat     = $bg['repeat']     ?? 'no-repeat';
    $attachment = $bg['attachment'] ?? 'scroll';
    $gradient   = $bg['gradient']   ?? '';

    if ( 'gradient' === $mode && $gradient ) {
        return 'background: ' . esc_attr( $gradient ) . ';';
    }

    if ( 'image' === $mode && $image_url ) {
        return implode( ' ', [
            'background-color: '      . esc_attr( $color )      . ';',
            'background-image: url('  . esc_url( $image_url )   . ');',
            'background-position: '   . esc_attr( $position )   . ';',
            'background-size: '       . esc_attr( $size )        . ';',
            'background-repeat: '     . esc_attr( $repeat )      . ';',
            'background-attachment: ' . esc_attr( $attachment )  . ';',
        ] );
    }

    return $color ? 'background-color: ' . esc_attr( $color ) . ';' : '';
}

php

// Usage
echo '<section class="hero"   style="' . mytheme_get_background_style( 'hero_background' )   . '">';
echo '<section class="footer" style="' . mytheme_get_background_style( 'footer_background' ) . '">';

With a conditional field

php

[
    'id'      => 'enable_custom_body_bg',
    'type'    => 'toggle',
    'title'   => __( 'Custom Body Background', 'your-textdomain' ),
    'default' => false,
],
[
    'id'       => 'body_background',
    'type'     => 'background',
    'title'    => __( 'Body Background', 'your-textdomain' ),
    'color'    => true,
    'image'    => true,
    'gradient' => true,
    'default'  => [
        'mode'       => 'color',
        'color'      => '#ffffff',
        'image'      => '',
        'position'   => 'center center',
        'size'       => 'cover',
        'repeat'     => 'no-repeat',
        'attachment' => 'scroll',
        'gradient'   => '',
    ],
    'required' => ['enable_custom_body_bg', '==', true],
],

---

Notes

• The image sub-key returns a full URL string — use it directly with esc_url(). Do not pass it to wp_get_attachment_image_url().
• Use the mode key to determine which background type is active ('color', 'image', or 'gradient') before building CSS — only apply image or gradient CSS when that mode is selected.
• Only color mode is enabled by default. Set 'image' => true and/or 'gradient' => true in the field config to show those tabs in the UI.
• Always use ?? null coalescing when reading sub-keys — a partially saved field may be missing some keys.
• For a single color only, use the Color Picker field. For a standalone gradient without image/color options, use the Gradient Picker field.