Checkbox

Overview

The Checkbox field creates a list of tick-able inputs.

Screenshots

Changelog

  • Return format setting added in version 5.4.0
  • Toggle all setting added in version 5.2.7

Settings

Name Description
Choices Each choice is entered on a new line (eg. ‘Red’). For more control over the value and label, you may use a ‘ : ‘ character to specify both (eg. ‘red : Red’)
Default Value Specify the default value(s) selected when first editing the field’s value. Enter only values (not labels)
Layout Changes the layout style of inputs from Vertical to Horizontal
Toggle Adds an extra checkbox above choices to toggle on/off all inputs
Return Format Change the value format returned by the get_field() and similar functions.
Allow Custom Appends a button, which when clicked, adds a text input to the list. Multiple custom values may be added and removed
Save Custom Saves any custom values to the field’s choices. Please see notes section for more information on this setting

Notes

Save Custom

If using the local JSON feature, any custom values saved to the field’s choices will not appear on page reload. This is because the JSON file will not be updated and will override any field settings found in the DB.

Template usage

The checkbox field will return an array of selected choices. Either use the get_field() function to obtain this array, or use the_field() to simply output the values, each value separated by a comma (if more than one).

Basic

This example shows how to display a coma separated list of selected values.

<p>Colors: <?php the_field('colors'); ?></p>

Custom

This example shows how to load and display multiple selected values.

<?php

// vars	
$colors = get_field('colors');


// check
if( $colors ): ?>
<ul>
	<?php foreach( $colors as $color ): ?>
		<li><?php echo $color; ?></li>
	<?php endforeach; ?>
</ul>
<?php endif; ?>

Display value and label

This example shows how to load a selected value and label without using the ‘Format value’ setting.

<?php

// vars	
$field = get_field_object('colors');
$colors = $field['value'];


// check
if( $colors ): ?>
<ul>
	<?php foreach( $colors as $color ): ?>
		<li><?php echo $field['choices'][ $color ]; ?></li>
	<?php endforeach; ?>
</ul>
<?php endif; ?>

Format value setting

This example shows how to load a selected value and label using the ‘Format value’ setting (set to ‘Both’).

<?php

// vars	
$colors = get_field('colors');


// check
if( $colors ): ?>
<ul>
	<?php foreach( $colors as $color ): ?>
		<li><span class="color-<?php echo $color['value']; ?>"><?php echo $color['label']; ?></span></li>
	<?php endforeach; ?>
</ul>
<?php endif; ?>

Conditional

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

<?php

// vars	
$colors = get_field('colors');


// check
if( $colors && in_array('red', $colors) ): ?>
<p>Selected the Red choice!</p>
<?php endif; ?>

Query posts

This example shows how to query posts that have the value ‘red’ selected. The checkbox field saves it’s value as a serialized array, so it is important to use the meta_query LIKE compare.

<?php

$posts = get_posts(array(
    'meta_query' => array(
        array(
            'key' => 'colors', // name of custom field
            'value' => '"red"', // matches exactly "red"
            'compare' => 'LIKE'
        )
    )
));

if( $posts ) {
    //...
}

?>

Related