Attention Interested in functions, hooks, classes, or methods? Check out the new WordPress Code Reference!

Class Reference/WP Customize Manager/add control


Displays a new controller on the Theme Customization admin screen (available in WordPress 3.4 or newer). Controls serve two purposes: they create a "physical" control that allows a user to manipulate a setting, and it also binds a pre-defined setting to a pre-defined section.

This is a method of the WP_Customize_Manager() class and can only be accessed through the $wp_customize object within the customize_register action hook.


$wp_customize->add_control($id, $args);


(mixed) (required) A string or a specific customization controller object.
Default: None
(array) (required) Not used if $id is a control object, otherwise an instance of WP_Customize_Control() (plain text) is created using the specified arguments.
Default: None


Optional. Displayed label. Example: 'label' => __( 'Base Color Scheme', 'twentyfifteen' ),
Optional. Example: 'description' => __( 'Applied to the header on small screens and the sidebar on wide screens.', 'twentyfifteen' ),
Any readily available or user defined section. Some available sections: themes, title_tagline, colors, header_image (only when enabled), background_image (only when enabled), static_front_page. Example: 'section' => 'colors',
Optional. themes (0), title_tagline (20), colors (40), header_image (60), background_image (80), static_front_page (120).
Supported types include: text, checkbox, radio, select, textarea, dropdown-pages, email, url, number, hidden, and date. Example: 'type' => 'textarea',
Optional. If in https://codex.wordpress.org/Class_Reference/WP_Customize_Manager/add_setting you specified "theme_mod" type then you should add here ID of the database setting which you want to modify, e.g. "header_color" (which is your arbitrary name specific to your theme only). It will be stored as a serialized value obtainable with https://codex.wordpress.org/Function_Reference/get_theme_mod like get_theme_mod('header_color');. If you selected "option" type in https://codex.wordpress.org/Class_Reference/WP_Customize_Manager/add_setting then you can add here a plain word like "theme_name_header_color" which will be obtainable with get_option('theme_name_header_color');. Serialized values like "my_namespace[header_color]" are allowed in both cases, however you probably don't need to serialize it when using "theme_mod" as it's already stored in the database as a serialized entry. If not defined, then the $id as the setting ID is used.
choices, height, width etc.
Optional. It's possible to pass custom parameters for specific control types. These are available only for some control types. Example for "select" and "radio" controls: 'choices'=> twentyfifteen_get_color_scheme_choices(),


Creates a control that allows users to enter plain text. This is also the parent class for the classes that follow.
Creates a control that allows users to select a color from a color wheel.
Creates a control that allows users to upload media.
Creates a control that allows users to select or upload an image.
Creates a control that allows users to select a new background image.
Creates a control that allows users to select a new header image.

Custom controls can also be created. For more information, see this post on Ottopress.com


Remember that this example assumes you are already working within the customize_register action hook.

$wp_customize->add_control( new WP_Customize_Color_Control( 
		'label'      => __( 'Header Color', 'mytheme' ),
		'section'    => 'your_section_id',
		'settings'   => 'your_setting_id',
	        'priority'   => 1

Alternatively, it is not required to instantiate a WP_Customize_Control object. WordPress will check to see if you are passing in an object and, if absent, will create a new WP_Customize_Control object with the arguments you have passed in.

		'label'    => __( 'Control Label', 'mytheme' ),
		'section'  => 'your_section_id',
		'settings' => 'your_setting_id',
		'type'     => 'radio',
		'choices'  => array(
			'left'  => 'left',
			'right' => 'right',

Note the 'type' argument is available to specify the input type of the control form element. For more information on these arguments, please refer to WP_Customize_Control


To force a specific image size see: WP_Customize_Cropped_Image_Control

See also index of Class Reference and index of Function Reference.