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

Option	Type	Required	Description
id	string	✅	Unique field identifier — used as the option key
type	string	✅	Must be image
title	string	✅	Label shown above the field
subtitle	string	—	Smaller descriptive text shown below the label
desc	string	—	Help text shown below the image selector
default	string	—	Default value — typically an empty string or a default image URL
required	array	—	Conditional logic rules — see Conditional Logic

---

Return Value

Type: int

Returns the WordPress attachment ID of the selected image as an integer, or an empty string if no image has been selected.

php

$logo_id = themeplus_get_option( 'logo_image', '' );
// Returns: 42 (attachment ID)

---

Usage Examples

Displaying the logo

php

$logo_id = themeplus_get_option( 'logo_image', '' );

if ( $logo_id ) {
    echo wp_get_attachment_image( $logo_id, 'full', false, [
        'class' => 'site-logo__img',
        'alt'   => get_bloginfo( 'name' ),
    ]);
}

Getting the image URL

php

$logo_id  = themeplus_get_option( 'logo_image', '' );
$logo_url = $logo_id ? wp_get_attachment_image_url( $logo_id, 'full' ) : '';

if ( $logo_url ) {
    echo '<img src="' . esc_url( $logo_url ) . '" alt="' . esc_attr( get_bloginfo('name') ) . '">';
}

As a CSS background image

php

$bg_id  = themeplus_get_option( 'hero_bg_image', '' );
$bg_url = $bg_id ? wp_get_attachment_image_url( $bg_id, 'full' ) : '';

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

With a fallback to a default theme image

php

$placeholder_id  = themeplus_get_option( 'default_thumbnail', '' );
$placeholder_url = $placeholder_id
    ? wp_get_attachment_image_url( $placeholder_id, 'medium' )
    : 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

[
    '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 attachment ID integer — always use WordPress functions like wp_get_attachment_image() or wp_get_attachment_image_url() to retrieve the image rather than constructing URLs manually.
• Use wp_get_attachment_image() over a plain <img> tag where possible — it handles srcset, sizes, lazy loading, and accessibility attributes automatically.
• Always check that the returned ID is truthy before using it, as the field returns an empty string when no image is selected.
• For selecting multiple images at once, use the Gallery field instead.