Button Set Field

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

Overview

The Button Set field renders a row of clickable buttons where only one can be active at a time. It returns the selected option’s key 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, sidebar position, style presets, and similar settings where seeing all options at a glance is more helpful than a dropdown.

For longer option lists use the Select field. For multiple selections use the Checkbox field. For a traditional radio button interface use the Radio field.

Field Registration

[
    'id'       => 'sidebar_position',
    'type'     => 'button_set',
    'title'    => __( 'Sidebar Position', 'your-textdomain' ),
    'subtitle' => __( 'Controls sidebar placement on archive and single pages', 'your-textdomain' ),
    'default'  => 'right',
    'options'  => [
        'left'  => __( 'Left', 'your-textdomain' ),
        'none'  => __( 'None', 'your-textdomain' ),
        'right' => __( 'Right', '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	—	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 on the button
default	string	—	Default selected value — must match a key in options
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 button, or the default value if nothing has been saved yet. Returns an empty string '' if no default is set and nothing has been saved.

$sidebar = themeplus_get_option( 'sidebar_position', 'right' );
// Returns: 'right'

Usage Examples

Applying a CSS modifier class

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

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

Text alignment

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

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

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

Sidebar position with conditional field

[
    'id'      => 'sidebar_position',
    'type'    => 'button_set',
    'title'   => __( 'Sidebar Position', 'your-textdomain' ),
    'default' => 'right',
    'options' => [
        'left'  => __( 'Left', 'your-textdomain' ),
        'none'  => __( 'None', 'your-textdomain' ),
        'right' => __( 'Right', 'your-textdomain' ),
    ],
],
[
    'id'       => 'sidebar_width',
    'type'     => 'slider',
    'title'    => __( 'Sidebar Width', 'your-textdomain' ),
    'default'  => 30,
    'min'      => 20,
    'max'      => 45,
    'unit'     => '%',
    'required' => ['sidebar_position', '!=', 'none'],
],

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

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

Header style with conditional color

[
    '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' ),
    'default'  => '#ffffff',
    'required' => ['header_style', '!=', 'transparent'],
],

As a conditional logic trigger

// Show or hide fields based on which button is selected
[
    'id'       => 'blog_layout',
    'type'     => 'button_set',
    'title'    => __( 'Blog Layout', 'your-textdomain' ),
    'default'  => 'grid',
    'options'  => [
        'grid'    => __( 'Grid', 'your-textdomain' ),
        'list'    => __( 'List', 'your-textdomain' ),
        'masonry' => __( 'Masonry', 'your-textdomain' ),
    ],
],
[
    'id'       => 'grid_columns',
    'type'     => 'button_set',
    'title'    => __( 'Grid Columns', 'your-textdomain' ),
    'default'  => '3',
    'options'  => [
        '2' => '2',
        '3' => '3',
        '4' => '4',
    ],
    'required' => ['blog_layout', '==', 'grid'],
],

Notes

• Button Set works best with 2 to 5 options — the buttons sit in a single row. For longer lists, use the Select field.
• The options array keys are what get stored and returned — keep them lowercase and stable across theme versions. Changing a key in a future version will cause saved values to no longer match.
• Only one button can be active at a time. For multiple selections, use the Checkbox field.
• For a traditional radio button interface, use the Radio field. For a searchable dropdown, use the Select field.