Radio Field

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

Last updated: March 11, 2026

Overview

The Radio field renders a vertical list of radio buttons where only one can be selected at a time. It returns the selected option value as a string. Use it when you want to present all available choices visibly at once and only allow a single selection — similar to Button Set but in a more traditional form style, suitable for longer option labels.

Field Registration

php

[
    'id'       => 'blog_layout',
    'type'     => 'radio',
    'title'    => __('Blog Layout', 'your-textdomain'),
    'subtitle' => __('Choose how blog posts are displayed', 'your-textdomain'),
    'default'  => 'grid',
    '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`	—	Smaller descriptive text shown below the label
`desc`	`string`	—	Help text shown below the radio buttons
`default`	`string`	—	Default selected value — must match a key in `options`
`options`	`array`	✅	Key-value pairs — key is stored, value is the label shown
`required`	`array`	—	Conditional logic rules — see Conditional Logic

Return Value

Type: string

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

php

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

Usage Examples

Applying a CSS class

php

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

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

Conditional template loading

php

$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;
}

Page title style

php

[
    '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'),
    ],
]

php

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

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

With a conditional field

php

[
    '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

Radio works best when all options need to be visible simultaneously and labels are descriptive. For short labels with 2 to 5 choices, Button Set is often a cleaner UI.
For a compact dropdown with many options, use the Select field instead.
Radio only allows selecting one option at a time. For multiple selections, use the Checkbox field.

Quick Links