Image Field

Overview

The Image field opens the WordPress media library and lets the user select or upload a single image. It returns the attachment ID of the selected image as an integer. Use it for logos, favicons, hero images, placeholder images, background images, or any other single image option in your theme.

Field Registration

php

[
    'id'      => 'logo_image',
    'type'    => 'image',
    'title'   => __('Logo Image', 'your-textdomain'),
    'subtitle' => __('Upload your theme logo', 'your-textdomain'),
    'default' => '',
]

Field Options

Return Value

Type: array

Returns a structured array with six keys, or an empty array [] when no image has been selected:

php

$logo = themeplus_get_option( 'logo_image', [] );
// Returns:
// [
//     'id'     => 42,        // int   — WordPress attachment ID
//     'url'    => 'https://example.com/wp-content/uploads/logo.png',
//     'width'  => 300,       // int   — image width in pixels
//     'height' => 100,       // int   — image height in pixels
//     'alt'    => 'My Logo', // string — alt text from Media Library
//     'title'  => 'Logo',    // string — title from Media Library
// ]
//
// Returns [] (empty array) when no image is selected.

Usage Examples

Displaying the logo

php

$logo = themeplus_get_option( 'logo_image', [] );

if ( ! empty( $logo['url'] ) ) {
    echo '<img src="' . esc_url( $logo['url'] ) . '" alt="' . esc_attr( $logo['alt'] ?: get_bloginfo( 'name' ) ) . '">';
}

Using WordPress image functions with the attachment ID

php

$logo = themeplus_get_option( 'logo_image', [] );

if ( ! empty( $logo['id'] ) ) {
    echo wp_get_attachment_image( $logo['id'], 'full', false, [
        'class' => 'site-logo__img',
        'alt'   => $logo['alt'] ?: get_bloginfo( 'name' ),
    ]);
}

Using width and height for explicit dimensions

$logo = themeplus_get_option( 'logo_image', [] );

if ( ! empty( $logo['url'] ) ) {
    printf(
        '<img src="%s" alt="%s" width="%d" height="%d">',
        esc_url( $logo['url'] ),
        esc_attr( $logo['alt'] ?: get_bloginfo( 'name' ) ),
        absint( $logo['width'] ),
        absint( $logo['height'] )
    );
}

As a CSS background image

php

$hero = themeplus_get_option( 'hero_bg_image', [] );

if ( ! empty( $hero['url'] ) ) {
    echo '<section class="hero" style="background-image: url(' . esc_url( $hero['url'] ) . ');">';
} else {
    echo '<section class="hero">';
}
echo '</section>';

With a fallback to a default theme image

php

$placeholder = themeplus_get_option( 'default_thumbnail', [] );
$placeholder_url = ! empty( $placeholder['url'] )
    ? $placeholder['url']
    : get_template_directory_uri() . '/assets/images/placeholder.jpg';

if ( ! has_post_thumbnail() ) {
    echo '<img src="' . esc_url( $placeholder_url ) . '" alt="">';
}

With a conditional field

php

// Config — no change needed here, conditional logic works the same
[
    'id'      => 'enable_custom_logo',
    'type'    => 'toggle',
    'title'   => __( 'Use Custom Logo', 'your-textdomain' ),
    'default' => false,
],
[
    'id'       => 'logo_image',
    'type'     => 'image',
    'title'    => __( 'Logo Image', 'your-textdomain' ),
    'required' => ['enable_custom_logo', '==', true],
],
[
    'id'       => 'logo_retina',
    'type'     => 'image',
    'title'    => __( 'Retina Logo (2x)', 'your-textdomain' ),
    'subtitle' => __( 'Optional high-resolution logo for retina displays', 'your-textdomain' ),
    'required' => ['enable_custom_logo', '==', true],
],

Notes

• The field returns an array with id, url, width, height, alt, and title keys — always check ! empty( $logo['url'] ) before using the value.
• Use $logo['url'] for direct output, or $logo['id'] with wp_get_attachment_image() when you need WordPress to handle srcset, sizes, lazy loading, and accessibility attributes automatically.
• The alt key reflects the alt text set in the Media Library. Fall back to get_bloginfo( 'name' ) for logos or a descriptive string for other images.
• Returns an empty array [] when no image is selected — not null, not 0, not an empty string.
• For selecting multiple images at once, use the Gallery field instead.