Button Group


The Button Group field provides a neat UI for selecting a value.



  • Added in version 5.6.3.


  • Choices
    The choices displayed when selecting a value. Enter each choice on a new line (eg. Red). For more control over the value and label, you may use a colon to specify both (eg. red : Red). You may also enter HTML as a choice as shown in the above screenshots.

  • Allow Null
    Allows no value to be selected.

  • Default Value
    The default values selected when first editing the field’s value. Enter only values, not labels.

  • Layout
    The layout orientation of the inputs. Select from “Vertical” or “Horizontal”.

  • Return Format
    Specifies the value format returned by ACF functions. Select from “Value”, “Label” or “Both”.

Template usage

Display value

This example demonstrates how to display the selected value using the Return Format setting Value.

<p>Color: <?php the_field('color'); ?></p>

Display value and label

This example demonstrates how to display the selected value and label using the Return Format setting Both.

$color = get_field('color');
<p>Color: <span class="color-<?php echo esc_attr($color['value']); ?>"><?php echo esc_html($color['label']); ?></span></p>


This example demonstrates how to use a selected value to conditionally perform a task.


if( get_field('color') == 'red' ) {
    // Do something.

Query Posts

This example demonstrates how to query posts that have a ‘red’ value for the field ‘color’.


$posts = get_posts( array(
    'meta_query' => array(
            'key'   => 'color',
            'value' => 'red',
) );

if( $posts ) {
    foreach( $posts as $post ) {
        // Do something.

⏰ It's finally time! ACF PRO pricing changes take effect on Monday, 24th February. Learn more

We use cookies to offer you a better browsing experience, analyze site traffic and personalize content. Read about how we use cookies and how you can control them in our Cookie Policy. If you continue to use this site, you consent to our use of cookies.