Button Set Field

A visual button group for selecting a single option from a small set of choices.

Last updated: March 11, 2026

Overview

The Button Set field renders a group of clickable buttons where only one can be active at a time. It returns the selected option value as a string. Use it as a more visual alternative to a Select dropdown when the number of choices is small — layout modes, alignment options, style presets, and similar settings where seeing all options at once is helpful.

Field Registration

php

[
    'id'       => 'content_layout',
    'type'     => 'button_set',
    'title'    => __('Content Layout', 'your-textdomain'),
    'subtitle' => __('Choose the main content layout', 'your-textdomain'),
    'default'  => 'boxed',
    'options'  => [
        'boxed'     => __('Boxed', 'your-textdomain'),
        'fullwidth' => __('Full Width', 'your-textdomain'),
    ],
]

Field Options

Option	Type	Required	Description
`id`	`string`	✅	Unique field identifier — used as the option key
`type`	`string`	✅	Must be `button_set`
`title`	`string`	✅	Label shown above the field
`subtitle`	`string`	—	Smaller descriptive text shown below the label
`desc`	`string`	—	Help text shown below the buttons
`default`	`string`	—	Default selected value — must match a key in `options`
`options`	`array`	✅	Key-value pairs — key is stored, value is the button label
`required`	`array`	—	Conditional logic rules — see Conditional Logic

Return Value

Type: string

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

php

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

Usage Examples

Applying a CSS class

php

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

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

Text alignment option

php

[
    'id'      => 'hero_text_align',
    'type'    => 'button_set',
    'title'   => __('Hero Text Alignment', 'your-textdomain'),
    'default' => 'left',
    'options' => [
        'left'   => __('Left', 'your-textdomain'),
        'center' => __('Center', 'your-textdomain'),
        'right'  => __('Right', 'your-textdomain'),
    ],
]

php

$align = themeplus_get_option( 'hero_text_align', 'left' );

echo '<style>
    .hero__content {
        text-align: ' . esc_attr( $align ) . ';
    }
</style>';

Sidebar position

php

[
    'id'      => 'sidebar_position',
    'type'    => 'button_set',
    'title'   => __('Sidebar Position', 'your-textdomain'),
    'default' => 'right',
    'options' => [
        'left'  => __('Left', 'your-textdomain'),
        'right' => __('Right', 'your-textdomain'),
        'none'  => __('No Sidebar', 'your-textdomain'),
    ],
]

php

$sidebar = themeplus_get_option( 'sidebar_position', 'right' );

if ( $sidebar !== 'none' ) {
    get_sidebar();
}

With a conditional field

php

[
    'id'      => 'header_style',
    'type'    => 'button_set',
    'title'   => __('Header Style', 'your-textdomain'),
    'default' => 'light',
    'options' => [
        'light'       => __('Light', 'your-textdomain'),
        'dark'        => __('Dark', 'your-textdomain'),
        'transparent' => __('Transparent', 'your-textdomain'),
    ],
],
[
    'id'       => 'header_bg_color',
    'type'     => 'color',
    'title'    => __('Header Background Color', 'your-textdomain'),
    'required' => ['header_style', '!=', 'transparent'],
],

Notes

Button Set works best with 2 to 5 options. For longer lists, use the Select field instead.
The options array keys are what get stored and returned — keep them lowercase and stable across theme versions.
Button Set only allows selecting one option at a time. For multiple selections, use the Checkbox field.
For a similar single-choice field with a more traditional UI, use the Radio field.

Quick Links