WordPress.org

Description

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.

Usage

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

Parameters

$id

(mixed) (required) A string or a specific customization controller object.

Default: None

$args

(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

Arguments

label

Optional. Displayed label. Example: 'label' => __( 'Base Color Scheme', 'twentyfifteen' ),

description

Optional. Example: 'description' => __( 'Applied to the header on small screens and the sidebar on wide screens.', 'twentyfifteen' ),

section

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',

priority

Optional. themes (0), title_tagline (20), colors (40), header_image (60), background_image (80), static_front_page (120).

type

Supported types include: text, checkbox, radio, select, textarea, dropdown-pages, email, url, number, hidden, and date. Example: 'type' => 'textarea',

settings

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(),

input_attrs

Optional. Allows you to add attributes to the input. This extends beyond just using min, max, and step for number and range, to the ability to add custom classes, placeholders, the pattern attribute, and anything else you need to the input element. These are available only for some control types. Example for "number" and "range" controls: 'input_attrs' => array( 'min' => 0, 'max' => 10, 'step' => 2 )

Classes

WP_Customize_Control()

Creates a control that allows users to enter plain text. This is also the parent class for the classes that follow.

WP_Customize_Color_Control()

Creates a control that allows users to select a color from a color wheel.

WP_Customize_Upload_Control()

Creates a control that allows users to upload media.

WP_Customize_Image_Control()

Creates a control that allows users to select or upload an image.

WP_Customize_Background_Image_Control()

Creates a control that allows users to select a new background image.

WP_Customize_Header_Image_Control()

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

Example

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

$wp_customize->add_control( new WP_Customize_Color_Control( 
	$wp_customize, 
	'your_control_id', 
	array(
		'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.

$wp_customize->add_control(
	'your_control_id', 
	array(
		'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

Related

• Info: Theme Customization API

• Class: WP_Customize_Manager() class
• Method: WP_Customize_Manager->add_setting()
• Method: WP_Customize_Manager->add_section()
• Method: WP_Customize_Manager->add_control()
• Method: WP_Customize_Manager->get_setting()
• Hook: customize_register
• Hook: customize_preview_init
• Hook: customize_controls_print_styles
• Hook: customize_controls_print_scripts
• Hook: customize_controls_init
• Hook: customize_controls_enqueue_scripts

To force a specific image size see: WP_Customize_Cropped_Image_Control