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'),
    'default' => [
        'color'      => '#0a0a0a',
        'image'      => '',
        'position'   => 'center center',
        'size'       => 'cover',
        'repeat'     => 'no-repeat',
        'attachment' => 'scroll',
    ],
]

---

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

Default Sub-options

Key	Type	Description
color	string	Background color — hex or rgba string
image	string	Background image — attachment ID (integer) or URL string
position	string	Background position — e.g. center center, top left
size	string	Background size — cover, contain, or a custom value like 100% auto
repeat	string	Background repeat — no-repeat, repeat, repeat-x, repeat-y
attachment	string	Background attachment — scroll or fixed

---

Return Value

Type: array

Returns an associative array with color, image, position, size, repeat, and attachment keys, or the default array if nothing has been saved yet.

php

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

---

Usage Examples

Applying as inline CSS

php

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

$color      = esc_attr( $bg['color']      ?? '#0a0a0a'       );
$image_id   = $bg['image'] ?? '';
$position   = esc_attr( $bg['position']   ?? 'center center' );
$size       = esc_attr( $bg['size']       ?? 'cover'         );
$repeat     = esc_attr( $bg['repeat']     ?? 'no-repeat'     );
$attachment = esc_attr( $bg['attachment'] ?? 'scroll'        );

$image_url = $image_id ? wp_get_attachment_image_url( (int) $image_id, 'full' ) : '';

$style  = 'background-color: ' . $color . ';';
if ( $image_url ) {
    $style .= 'background-image: url(' . esc_url( $image_url ) . ');';
    $style .= 'background-position: ' . $position   . ';';
    $style .= 'background-size: '     . $size       . ';';
    $style .= 'background-repeat: '   . $repeat     . ';';
    $style .= 'background-attachment: ' . $attachment . ';';
}

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

CSS custom properties

php

$bg       = themeplus_get_option( 'body_background', [] );
$image_id = $bg['image'] ?? '';
$image_url = $image_id ? wp_get_attachment_image_url( (int) $image_id, 'full' ) : 'none';

echo '<style>
    :root {
        --body-bg-color:      ' . esc_attr( $bg['color']      ?? '#ffffff'       ) . ';
        --body-bg-image:      url(' . esc_url( $image_url )                        . ');
        --body-bg-position:   ' . esc_attr( $bg['position']   ?? 'center center' ) . ';
        --body-bg-size:       ' . esc_attr( $bg['size']       ?? 'cover'         ) . ';
        --body-bg-repeat:     ' . esc_attr( $bg['repeat']     ?? 'no-repeat'     ) . ';
        --body-bg-attachment: ' . esc_attr( $bg['attachment'] ?? 'scroll'        ) . ';
    }
</style>';

Helper function for reuse

php

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

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

    $color      = esc_attr( $bg['color']      ?? ''             );
    $image_id   = $bg['image'] ?? '';
    $position   = esc_attr( $bg['position']   ?? 'center center' );
    $size       = esc_attr( $bg['size']       ?? 'cover'         );
    $repeat     = esc_attr( $bg['repeat']     ?? 'no-repeat'     );
    $attachment = esc_attr( $bg['attachment'] ?? 'scroll'        );
    $image_url  = $image_id ? wp_get_attachment_image_url( (int) $image_id, 'full' ) : '';

    $css = $selector . ' {';
    if ( $color )     $css .= 'background-color: ' . $color . ';';
    if ( $image_url ) {
        $css .= 'background-image: url(' . esc_url( $image_url ) . ');';
        $css .= 'background-position: '   . $position   . ';';
        $css .= 'background-size: '       . $size       . ';';
        $css .= 'background-repeat: '     . $repeat     . ';';
        $css .= 'background-attachment: ' . $attachment . ';';
    }
    $css .= '}';

    return $css;
}

php

// Usage
$styles  = mytheme_background_css( 'body',     'body_background'  );
$styles .= mytheme_background_css( '.hero',    'hero_background'  );
$styles .= mytheme_background_css( '.footer',  'footer_background' );

echo '<style>' . $styles . '</style>';

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'),
    'default'  => [
        'color'      => '#ffffff',
        'image'      => '',
        'position'   => 'center center',
        'size'       => 'cover',
        'repeat'     => 'no-repeat',
        'attachment' => 'scroll',
    ],
    'required' => ['enable_custom_body_bg', '==', true],
],

---

Notes

• The image sub-key returns a WordPress attachment ID as an integer — always pass it to wp_get_attachment_image_url() to get the URL rather than using it directly.
• Always check $image_id is truthy before calling wp_get_attachment_image_url() — the field returns an empty string when no image is selected.
• Always use the ?? null coalescing operator when reading individual sub-keys, since a partially saved field may be missing some keys.
• For a single color only, use the Color Picker field. For a gradient background, use the Gradient Picker field.