Button Group

A segmented button row that replaces a standard radio or checkbox group with styled toggle buttons. Supports single-select (radio) and multi-select (checkbox) modes and can return the value, label, or both.

Settings

Setting	Default	Options	Description
Choices	(empty)	—	One choice per line, in the format `value : label`.
Multiple	`false`	on/off	Allow selecting more than one option at once.
Return Format	`value`	`value` · `label` · `array`	Controls what `get_field()` returns.

Choices format

left : Left
center : Center
right : Right

Return values

Single select

`return_format: 'value'`

$alignment = get_field('text_alignment');
// "center"

`return_format: 'label'`

$alignment = get_field('text_alignment');
// "Center"

`return_format: 'array'`

$alignment = get_field('text_alignment');
// ['value' => 'center', 'label' => 'Center']

Multi-select (`multiple: true`)

With multiple enabled, get_field() returns an array regardless of format.

$sizes = get_field('available_sizes');
// ['sm', 'md', 'lg']  (return_format: 'value')
// ['Small', 'Medium', 'Large']  (return_format: 'label')

Usage

Controlling layout via button group

$layout = get_field('section_layout'); // "grid" | "list" | "cards"

$class_map = [
    'grid'  => 'section--grid',
    'list'  => 'section--list',
    'cards' => 'section--cards',
];

$class = $class_map[$layout] ?? '';
echo '<section class="section ' . esc_attr($class) . '">';

Multi-select: filtering displayed items

$types = get_field('show_post_types'); // ['post', 'project']

if ($types) {
    $posts = get_posts(['post_type' => $types, 'posts_per_page' => 12]);
}

Rendering selected labels as badges

$features = get_field('product_features'); // return_format: 'label', multiple: true
if ($features) {
    foreach ($features as $label) {
        echo '<span class="feature-badge">' . esc_html($label) . '</span>';
    }
}