Adding a Select Control Using the WordPress Customizer API

A select control allows you to pick one of many values for a theme setting. It acts as an user interface for that setting.

To use the control you need to show it somewhere. The WordPress customizer screen is the best place for that.

The code for a select control is as follows –

$wp_customize->add_control( 'setting_id', array(
	'type' => 'select',
	'section' => 'section_id', // required - section id
	'label' => __( 'Select Header Layout', 'text-domain' ), // arbitrary string
	'description' => __( 'Custom header layout', 'text-domain' ), // arbitrary string
	'choices' => array(  // arbitrary values as an array
	     'center' => __( 'Center', 'text-domain' ),
	     'wide' => __( 'Wide', 'text-domain' )
	),
  ) );

The above code creates a select control with options center and wide ( as given in the choices array ).

The control is used for managing a setting with setting_id and is grouped inside a section with id section_id.

The setting and section should exist or you have to create them.

This code for creating the control should go inside a callback function which is associated with an action hook customize_register.

function custom_callback_function ( $wp_customize ) {
   // call to create a panel - Optional
   // call to create a section - Optional
   // call to create a setting - Required

   // call to create a control
   $wp_customize->add_control( 'setting_id', array(
	'type' => 'select',
	'section' => 'section_id', 
	'label' => __( 'Select Header Layout', 'text-domain' ), 
	'description' => __( 'Custom header layout', 'text-domain' ), 
	'choices' => array(  
	     'center' => __( 'Center', 'text-domain' ),
	     'wide' => __( 'Wide', 'text-domain' )
	 )
      ) 
    );

}
add_action( 'customize_register', 'custom_callback_function' ); 

And this complete code should be placed in the functions.php file of your custom theme.

The select control is a convenient way to manage a setting that can take one out of multiple values.

There is another type of select control with type dropdown-pages instead of select. This control lets you select any of the pages from all pages in the WordPress site.

The syntax for dropdown-pages is as follows –


   $wp_customize->add_control( 'setting_id', array(
	  'type' => 'dropdown-pages',
	  'section' => 'section_id', 
	  'label' => __( 'Select Header Layout', 'text-domain' ), 
	  'description' => __( 'Custom header layout', 'text-domain' ),      
        ) 
    );

The dropdown-pages control give us a quick way to pick a page from multiple options.

As with other controls, this control should also be written in a callback function written for the customize_register hook.

You can get the value of the setting associated with the select/dropdown-pages control by using get_theme_mod function.

So, if the id of the setting managed by the control is custom_select_setting_value then its value can be obtained with –

$custom_select_setting_value = get_theme_mod( 'custom_select_setting_value' );

You can then use this value in appropriate location in your custom theme.