Checkbox Field

A group of checkboxes for selecting one or more options from a list.

Overview

The Checkbox field renders a list of checkboxes where any number can be selected at once. It returns an array of the selected option keys. Use it when users need to enable multiple items simultaneously — header elements, visible sections, active features, post meta items, or any other multi-select scenario.

For selecting only one option at a time, use the Radio or Button Set field instead.

Field Registration

[
    'id'       => 'header_elements',
    'type'     => 'checkbox',
    'title'    => __( 'Header Elements', 'your-textdomain' ),
    'subtitle' => __( 'Choose which elements to show in the header', 'your-textdomain' ),
    'default'  => ['logo', 'navigation', 'search'],
    'layout'   => 'horizontal',
    'compact'  => true,
    'options'  => [
        'logo'       => __( 'Logo', 'your-textdomain' ),
        'navigation' => __( 'Navigation', 'your-textdomain' ),
        'search'     => __( 'Search', 'your-textdomain' ),
        'cart'       => __( 'Cart Icon', 'your-textdomain' ),
        'social'     => __( 'Social Icons', 'your-textdomain' ),
    ],
]

Field Options

Option	Type	Required	Description
id	string	✅	Unique field identifier — used as the option key
type	string	✅	Must be checkbox
title	string	✅	Label shown above the field
subtitle	string	—	Descriptive text shown below the label
desc	string	—	Alternative to subtitle — shown in the same position
options	array	✅	'key' => 'Label'map — key is stored, label is shown beside each checkbox
default	array	—	Array of keys checked by default
layout	string	—	Checkbox orientation — 'vertical'(default) or 'horizontal'
size	string	—	Checkbox size — 'small', 'medium' (default), or 'large'
compact	bool	—	Reduce spacing between checkboxes. Default: false
required	array	—	Conditional logic rules — see Conditional Logic

subtitle and desc serve the same purpose and render in the same position. If both are provided, subtitle takes priority.

Return Value

Type: array

Returns an array of the selected option keys, or the defaultarray if nothing has been saved yet. Returns an empty array [] if nothing is selected and no default is set.

$elements = themeplus_get_option( 'header_elements', ['logo', 'navigation', 'search'] );
// Returns: ['logo', 'navigation', 'search']

Usage Examples

Checking if a specific item is selected

$elements = themeplus_get_option( 'header_elements', [] );

if ( in_array( 'search', $elements, true ) ) {
    get_template_part( 'template-parts/header/search' );
}

if ( in_array( 'cart', $elements, true ) ) {
    get_template_part( 'template-parts/header/cart' );
}

Looping through selected values

$features = themeplus_get_option( 'enabled_features', [] );

if ( ! empty( $features ) ) {
    echo '<ul class="feature-list">';
    foreach ( $features as $feature ) {
        echo '<li class="feature feature--' . esc_attr( $feature ) . '">' . esc_html( $feature ) . '</li>';
    }
    echo '</ul>';
}

Post meta items to display

[
    'id'      => 'post_meta_items',
    'type'    => 'checkbox',
    'title'   => __( 'Post Meta Items', 'your-textdomain' ),
    'default' => ['date', 'author'],
    'layout'  => 'horizontal',
    'compact' => true,
    'options' => [
        'date'     => __( 'Date', 'your-textdomain' ),
        'author'   => __( 'Author', 'your-textdomain' ),
        'category' => __( 'Category', 'your-textdomain' ),
        'comments' => __( 'Comments', 'your-textdomain' ),
        'tags'     => __( 'Tags', 'your-textdomain' ),
    ],
]

$meta = themeplus_get_option( 'post_meta_items', ['date', 'author'] );

echo '<div class="post-meta">';
if ( in_array( 'date', $meta, true ) ) {
    echo '<span class="post-meta__date">' . esc_html( get_the_date() ) . '</span>';
}
if ( in_array( 'author', $meta, true ) ) {
    echo '<span class="post-meta__author">' . esc_html( get_the_author() ) . '</span>';
}
if ( in_array( 'category', $meta, true ) ) {
    the_category( ', ' );
}
echo '</div>';

Adding body classes from selections

$body_classes = themeplus_get_option( 'body_classes', [] );

add_filter( 'body_class', function( $classes ) use ( $body_classes ) {
    if ( is_array( $body_classes ) ) {
        foreach ( $body_classes as $class ) {
            $classes[] = sanitize_html_class( $class );
        }
    }
    return $classes;
} );

With conditional logic using contains

[
    'id'      => 'header_elements',
    'type'    => 'checkbox',
    'title'   => __( 'Header Elements', 'your-textdomain' ),
    'default' => ['logo', 'navigation'],
    'options' => [
        'logo'       => __( 'Logo', 'your-textdomain' ),
        'navigation' => __( 'Navigation', 'your-textdomain' ),
        'search'     => __( 'Search', 'your-textdomain' ),
        'cart'       => __( 'Cart Icon', 'your-textdomain' ),
    ],
],
[
    'id'       => 'search_placeholder',
    'type'     => 'text',
    'title'    => __( 'Search Placeholder Text', 'your-textdomain' ),
    'default'  => __( 'Search…', 'your-textdomain' ),
    'required' => ['header_elements', 'contains', 'search'],
],
[
    'id'       => 'cart_icon_style',
    'type'     => 'button_set',
    'title'    => __( 'Cart Icon Style', 'your-textdomain' ),
    'default'  => 'filled',
    'options'  => [
        'filled'   => __( 'Filled', 'your-textdomain' ),
        'outlined' => __( 'Outlined', 'your-textdomain' ),
    ],
    'required' => ['header_elements', 'contains', 'cart'],
],

Notes

• Always check ! empty( $value ) or is_array( $value )before looping — the field returns an empty array [] when nothing is selected.
• Use in_array( $key, $array, true ) with strict comparison (true) for reliable single-item checks.
• The contains and !contains conditional logic operators work directly with Checkbox values — see Conditional Logicfor the full syntax.
• Use layout => 'horizontal' with compact => true for tight inline checkbox rows (e.g. meta items). Use layout => 'vertical' (default) for longer label text.
• For selecting only one option at a time, use the Radio or Button Set field.