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. |
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 a coma separated list.
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 ) {
//...
}
?>