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 comma 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 ) {
//...
}
?>