Radio Field

A group of radio buttons for selecting a single option from a list.

Overview

The Radio field renders a list of radio buttons where only one can be selected at a time. It returns the selected option’s key as a string. Use it when you want all choices visible at once with descriptive labels — similar to Button Set but in a traditional form style that works well for longer option text.

For short labels with 2–5 choices, Button Set is often a cleaner UI. For a compact searchable dropdown, use the Select field. For multiple selections, use the Checkbox field.

Field Registration

[
    'id'       => 'blog_layout',
    'type'     => 'radio',
    'title'    => __( 'Blog Layout', 'your-textdomain' ),
    'subtitle' => __( 'Choose how blog posts are displayed', 'your-textdomain' ),
    'default'  => 'grid',
    'layout'   => 'horizontal',
    'options'  => [
        'grid'    => __( 'Grid', 'your-textdomain' ),
        'list'    => __( 'List', 'your-textdomain' ),
        'masonry' => __( 'Masonry', 'your-textdomain' ),
    ],
]

Field Options

Option	Type	Required	Description
id	string	✅	Unique field identifier — used as the option key
type	string	✅	Must be radio
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	✅	'key' => 'Label'map — key is stored, label is shown beside the radio button
default	string	—	Default selected value — must match a key in options
layout	string	—	Radio button orientation — 'vertical'(default) or 'horizontal'
size	string	—	Radio button size — 'small', 'medium' (default), or 'large'
compact	bool	—	Reduce spacing between radio buttons. Default: false
required	array	—	Conditional logic rules — see Conditional Logic

subtitle and desc serve the same purpose and render in the same position. If both are provided, subtitle takes priority.

Return Value

Type: string

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

$layout = themeplus_get_option( 'blog_layout', 'grid' );
// Returns: 'grid'

Usage Examples

Applying a CSS modifier class

$blog_layout = themeplus_get_option( 'blog_layout', 'grid' );

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

Conditional template loading

$blog_layout = themeplus_get_option( 'blog_layout', 'grid' );

switch ( $blog_layout ) {
    case 'list':
        get_template_part( 'template-parts/blog/list' );
        break;
    case 'masonry':
        get_template_part( 'template-parts/blog/masonry' );
        break;
    default:
        get_template_part( 'template-parts/blog/grid' );
        break;
}

Horizontal layout with compact spacing

[
    'id'      => 'archive_layout',
    'type'    => 'radio',
    'title'   => __( 'Archive Layout', 'your-textdomain' ),
    'default' => 'grid',
    'layout'  => 'horizontal',
    'compact' => true,
    'options' => [
        'grid' => __( 'Grid', 'your-textdomain' ),
        'list' => __( 'List', 'your-textdomain' ),
    ],
]

Page title style with descriptive labels

[
    'id'      => 'page_title_style',
    'type'    => 'radio',
    'title'   => __( 'Page Title Style', 'your-textdomain' ),
    'default' => 'standard',
    'options' => [
        'standard'   => __( 'Standard — title only', 'your-textdomain' ),
        'breadcrumb' => __( 'With Breadcrumbs', 'your-textdomain' ),
        'large'      => __( 'Large Hero Style', 'your-textdomain' ),
        'none'       => __( 'Hidden', 'your-textdomain' ),
    ],
]

$title_style = themeplus_get_option( 'page_title_style', 'standard' );

if ( 'none' !== $title_style ) {
    get_template_part( 'template-parts/page-title', $title_style );
}

With a conditional field

[
    'id'      => 'preloader_style',
    'type'    => 'radio',
    'title'   => __( 'Preloader Style', 'your-textdomain' ),
    'default' => 'spinner',
    'options' => [
        'spinner'  => __( 'Spinner', 'your-textdomain' ),
        'logo'     => __( 'Logo', 'your-textdomain' ),
        'progress' => __( 'Progress Bar', 'your-textdomain' ),
    ],
],
[
    'id'       => 'preloader_logo',
    'type'     => 'image',
    'title'    => __( 'Preloader Logo', 'your-textdomain' ),
    'required' => ['preloader_style', '==', 'logo'],
],

Notes

• The options array keys are what get stored and returned — keep them lowercase and stable across theme versions.
• Use layout => 'horizontal' for short labels (Left / Center / Right) and layout => 'vertical' (default) for longer descriptive labels.
• compact reduces the gap between radio buttons — useful when listing many options in a small space.
• Radio only allows selecting one option at a time. For multiple selections, use the Checkbox field.
• For short labels with 2–5 choices, Button Set is often a cleaner UI. For a searchable dropdown with many options, use the Select field.