Select Image Field

A visual image-based selector for choosing a single layout or style preset.

Overview

The Select Image field renders a set of clickable image thumbnails where only one can be selected at a time. It returns the selected option’s value as a string. Use it for layout presets, skin selections, blog template choices, or any option where showing a visual preview makes the choice clearer than a text label alone.

For text-only single-choice fields, use the Button Set or Radio field instead.

Field Registration

[
    'id'       => 'blog_template',
    'type'     => 'select_image',
    'title'    => __( 'Blog Template', 'your-textdomain' ),
    'subtitle' => __( 'Choose how blog posts are displayed', 'your-textdomain' ),
    'default'  => 'grid',
    'options'  => [
        [
            'value' => 'grid',
            'label' => __( 'Grid', 'your-textdomain' ),
            'image' => get_template_directory_uri() . '/assets/images/layouts/grid.png',
        ],
        [
            'value' => 'masonry',
            'label' => __( 'Masonry', 'your-textdomain' ),
            'image' => get_template_directory_uri() . '/assets/images/layouts/masonry.png',
        ],
        [
            'value' => 'rows',
            'label' => __( 'Rows', 'your-textdomain' ),
            'image' => get_template_directory_uri() . '/assets/images/layouts/rows.png',
        ],
    ],
]

Field Options

Option	Type	Required	Description
id	string	✅	Unique field identifier — used as the option key
type	string	✅	Must be select_image
title	string	✅	Label shown above the field
subtitle	string	—	Descriptive text shown below the label
desc	string	—	Alternative to subtitle — shown in the same position
options	array	✅	Array of option rows — each row has value, label, and image keys (see below)
default	string	—	Default selected value — must match a value in the options array
required	array	—	Conditional logic rules — see Conditional Logic

Option Row Structure

Each item in the options array is a row with these three keys:

Key	Type	Required	Description
value	string	✅	The value stored in the database when this option is selected
label	string	✅	Text label shown below the image thumbnail
image	string	✅	Full URL to the preview image

Important: The options format for Select Image is an array of rows — not a 'key' => 'Label' map like Select, Radio, Button Set, and Checkbox. Each option is its own array with value, label, and image keys.

Return Value

Type: string

Returns the value of the selected option row, or the defaultvalue if nothing has been saved yet. Returns an empty string ''if no default is set and nothing has been saved.

$template = themeplus_get_option( 'blog_template', 'grid' );
// Returns: 'grid'

Usage Examples

Applying a CSS modifier class

$template = themeplus_get_option( 'blog_template', 'grid' );

echo '<div class="blog-archive blog-archive--' . esc_attr( $template ) . '">';

Loading a template part by selection

$template = themeplus_get_option( 'blog_template', 'grid' );

get_template_part( 'template-parts/blog/' . sanitize_key( $template ) );

Header skin selection

[
    'id'      => 'header_skin',
    'type'    => 'select_image',
    'title'   => __( 'Header Skin', 'your-textdomain' ),
    'default' => 'classic',
    'options' => [
        [
            'value' => 'classic',
            'label' => __( 'Classic', 'your-textdomain' ),
            'image' => get_template_directory_uri() . '/assets/images/skins/header-classic.png',
        ],
        [
            'value' => 'dark',
            'label' => __( 'Dark', 'your-textdomain' ),
            'image' => get_template_directory_uri() . '/assets/images/skins/header-dark.png',
        ],
        [
            'value' => 'minimal',
            'label' => __( 'Minimal', 'your-textdomain' ),
            'image' => get_template_directory_uri() . '/assets/images/skins/header-minimal.png',
        ],
    ],
]

$skin = themeplus_get_option( 'header_skin', 'classic' );

echo '<header class="site-header site-header--' . esc_attr( $skin ) . '">';

With a conditional field

[
    'id'      => 'blog_template',
    'type'    => 'select_image',
    'title'   => __( 'Blog Template', 'your-textdomain' ),
    'default' => 'grid',
    'options' => [
        [
            'value' => 'grid',
            'label' => __( 'Grid', 'your-textdomain' ),
            'image' => get_template_directory_uri() . '/assets/images/layouts/grid.png',
        ],
        [
            'value' => 'masonry',
            'label' => __( 'Masonry', 'your-textdomain' ),
            'image' => get_template_directory_uri() . '/assets/images/layouts/masonry.png',
        ],
        [
            'value' => 'rows',
            'label' => __( 'Rows', 'your-textdomain' ),
            'image' => get_template_directory_uri() . '/assets/images/layouts/rows.png',
        ],
    ],
],
[
    'id'       => 'grid_columns',
    'type'     => 'button_set',
    'title'    => __( 'Grid Columns', 'your-textdomain' ),
    'default'  => '3',
    'options'  => [
        '2' => '2',
        '3' => '3',
        '4' => '4',
    ],
    'required' => ['blog_template', '==', 'grid'],
],

Notes

• The options format is an array of rows — each row has value, label, and image keys. This is different from Select, Radio, Button Set, and Checkbox which use a 'key' => 'Label' map.
• The field returns only the selected value string — not the label or image URL.
• Preview images are supplied by your theme — store them in your theme’s assets folder and reference them with get_template_directory_uri(). Thumbnails around 160×100px work well in the panel.
• Always use sanitize_key() or esc_attr() when using the returned value in CSS classes or template part names.