Select Image Field

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 key as a string. Use it for layout presets, skin selections, pattern choices, or any option where showing a visual preview makes the choice clearer than a text label alone.

---

Field Registration

php

[
    'id'       => 'site_layout',
    'type'     => 'select_image',
    'title'    => __('Site Layout', 'your-textdomain'),
    'subtitle' => __('Choose the overall site layout', 'your-textdomain'),
    'default'  => 'boxed',
    'options'  => [
        'boxed'     => [
            'label' => __('Boxed', 'your-textdomain'),
            'image' => get_template_directory_uri() . '/assets/images/layouts/boxed.png',
        ],
        'fullwidth' => [
            'label' => __('Full Width', 'your-textdomain'),
            'image' => get_template_directory_uri() . '/assets/images/layouts/fullwidth.png',
        ],
        'framed'    => [
            'label' => __('Framed', 'your-textdomain'),
            'image' => get_template_directory_uri() . '/assets/images/layouts/framed.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	—	Smaller descriptive text shown below the label
desc	string	—	Help text shown below the images
default	string	—	Default selected value — must match a key in options
options	array	✅	Key-value pairs — each value is an array with label and image keys
required	array	—	Conditional logic rules — see Conditional Logic

Option Item Structure

Each item in the options array must be an associative array with the following keys:

Key	Type	Required	Description
label	string	✅	Text label shown below the image thumbnail
image	string	✅	Full URL to the preview image

---

Return Value

Type: string

Returns the key of the selected option, or the default value if nothing has been saved yet.

php

$layout = themeplus_get_option( 'site_layout', 'boxed' );
// Returns: 'boxed'

---

Usage Examples

Applying a CSS class

php

$layout = themeplus_get_option( 'site_layout', 'boxed' );

echo '<div class="site-wrapper site-wrapper--' . esc_attr( $layout ) . '">';

Header skin selection

php

[
    'id'      => 'header_skin',
    'type'    => 'select_image',
    'title'   => __('Header Skin', 'your-textdomain'),
    'default' => 'skin-1',
    'options' => [
        'skin-1' => [
            'label' => __('Default', 'your-textdomain'),
            'image' => get_template_directory_uri() . '/assets/images/skins/header-1.png',
        ],
        'skin-2' => [
            'label' => __('Dark', 'your-textdomain'),
            'image' => get_template_directory_uri() . '/assets/images/skins/header-2.png',
        ],
        'skin-3' => [
            'label' => __('Minimal', 'your-textdomain'),
            'image' => get_template_directory_uri() . '/assets/images/skins/header-3.png',
        ],
    ],
]

php

$skin = themeplus_get_option( 'header_skin', 'skin-1' );

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

With a conditional field

php

[
    'id'      => 'blog_style',
    'type'    => 'select_image',
    'title'   => __('Blog Style', 'your-textdomain'),
    'default' => 'grid',
    'options' => [
        'grid'    => [
            'label' => __('Grid', 'your-textdomain'),
            'image' => get_template_directory_uri() . '/assets/images/blog/grid.png',
        ],
        'list'    => [
            'label' => __('List', 'your-textdomain'),
            'image' => get_template_directory_uri() . '/assets/images/blog/list.png',
        ],
        'masonry' => [
            'label' => __('Masonry', 'your-textdomain'),
            'image' => get_template_directory_uri() . '/assets/images/blog/masonry.png',
        ],
    ],
],
[
    'id'       => 'grid_columns',
    'type'     => 'button_set',
    'title'    => __('Grid Columns', 'your-textdomain'),
    'default'  => '3',
    'options'  => [
        '2' => '2',
        '3' => '3',
        '4' => '4',
    ],
    'required' => ['blog_style', '==', 'grid'],
],

---

Notes

• Preview images are supplied by your theme — store them in your theme’s assets/images/ folder and reference them with get_template_directory_uri().
• Keep preview images small and consistent in size — thumbnails around 160×100px work well in the options panel.
• The field returns only the option key as a string, not the image URL — use the key to apply CSS classes or load template parts.
• For a text-only version of this field, use the Button Set or Radio field instead.