Multiple Select Lists in the Theme Customizer

WordPress 3.4 introducted the Theme Customizer feature which allows site admins to tweak a theme’s settings and live preview those changes in real time.

In this post, I’ll give you a custom control class makes it possible to add a multiple select list to your theme customizer settings.

How to add the settings is not the focus of this post so you should check out posts like “How to leverage the Theme Customizer in your own themes” instead for great explaining on how to use the feature.

By default WordPress have controls for stuff like text fields, check boxes, color wheels, select lists, and image handling. But there’s no way to use a select list with the ‘multiple’ attribute unless you extend the WP_Customize_Control class.

By “multiple select lists”, I mean lists like this:

Creating the Class

I won’t go into much detail on how to create your own class as it’s already explained in Otto on WordPress’ great tutorial on how to create a custom control.

As explained in Otto’s post, the first step is to create a function that’s hooked into the customize_register action. This makes sure our class only is loaded when necessary.

add_action( 'customize_register', 'your_theme_customize_register' );

function your_theme_customize_register( $wp_customize ) {
    // Our class here
}

The content of the function will be our class with the multiple select control. We’re using in_array to detect whether or not the select items should be selected.

/**
 * Multiple select customize control class.
 */
class Jayj_Customize_Control_Multiple_Select extends WP_Customize_Control {

    /**
     * The type of customize control being rendered.
     */
    public $type = 'multiple-select';

    /**
     * Displays the multiple select on the customize screen.
     */
    public function render_content() {

    if ( empty( $this->choices ) )
        return;
    ?>
        <label>
            <span class="customize-control-title"><?php echo esc_html( $this->label ); ?></span>
            <select <?php $this->link(); ?> multiple="multiple" style="height: 100%;">
                <?php
                    foreach ( $this->choices as $value => $label ) {
                        $selected = ( in_array( $value, $this->value() ) ) ? selected( 1, 1, false ) : '';
                        echo '<option value="' . esc_attr( $value ) . '"' . $selected . '>' . $label . '</option>';
                    }
                ?>
            </select>
        </label>
    <?php }
}

Using the new control in the Customizer

Now that the new control has been created, it’s time to use it. Assuming you’ve already created some options in the customizer it should be easy to use the new control.

First we create the setting, then we create our control, by using the new Jayj_Customize_Control_Multiple_Select class.

$wp_customize->add_setting( 'multiple_select_setting', array(
    'default' => array(), // Either empty or fill it with your default values
) );
 
$wp_customize->add_control(
    new Jayj_Customize_Control_Multiple_Select(
        $wp_customize,
        'multiple_select_setting',
        array(
            'settings' => 'multiple_select_setting',
            'label'    => 'Testing multiple select',
            'section'  => 'themedemo_demo_settings', // Enter the name of your own section
            'type'     => 'multiple-select', // The $type in our class
            'choices'  => array( 'google' => 'Google', 'bing' => 'Bing' ) // Your choices
        )
    )
);
Example of the multiple select class in the Theme Customizer section of my Cakifo theme.
Example of the multiple select class in use in my Cakifo theme.

It’s all! If you have any comments, feel free to comment in this post.

Posted in on
3 likes

2 responses

Leave a Reply