How To extend WP_Customize_Control

I’m looking for a way to add a new kind of control to the customize live preview panel. I have seen how to add new sections to the panel using
add_action( 'customize_register'...

The control I want to implement is a different kind of color picker. In a previous post, we see how to extend core classes to add widgets, but what I lack here is a hook that will enable me to bring my object into scope – WP_Customize_Palette_Control. At

You can see the beginnings of the code here. This code is in the functions.php file of my theme.

Thanks for any help.

Just updated the code. Now I have require_once to bring in the classes. So now I have no PHP errors but my new control HTML does not appear.


require_once( ABSPATH . WPINC . '/class-wp-customize-setting.php' );
require_once( ABSPATH . WPINC . '/class-wp-customize-section.php' );
require_once( ABSPATH . WPINC . '/class-wp-customize-control.php' );

class WP_Customize_Palette_Control extends WP_Customize_Image_Control {  
        public $type="palette";
        public $removed = '';
        public $context;

        public function enqueue() {
                //wp_enqueue_script( 'wp-plupload' );

        public function to_json() {

                $this->json['removed'] = $this->removed;

                if ( $this->context )
                        $this->json['context'] = $this->context;

        public function render_content() {
                        <span class="customize-control-title"><?php echo esc_html( $this->label ); ?></span>
                                <a href="#" class="button-secondary upload"><?php _e( 'Upload' ); ?></a>
                                <a href="#" class="remove"><?php _e( 'Remove' ); ?></a>

//new WP_Customize_Palette_Control();

//add_action('customize_controls_init', 'WP_Customize_Palette_Control');

// add an option to the customize panel

function sci_customize_controls_init($wp_customize) {
    $wp_customize->add_section( 'themename_color_scheme', array(
        'title'          => __( 'Color Scheme', 'themename' ),
        'priority'       => 35,
    ) );

    $wp_customize->add_setting( 'themename_theme_options[color_scheme]', array(
    'default'        => 'some-default-value',
    'type'           => 'option',
    'capability'     => 'edit_theme_options',
) );

$wp_customize->add_control( 'themename_color_scheme', array(
    'label'      => __( 'Color Scheme', 'themename' ),
    'section'    => 'themename_color_scheme',
    'settings'   => 'themename_theme_options[color_scheme]',
    'type'       => 'palette',
    'choices'    => array(
        'value1' => 'Choice 1',
        'value2' => 'Choice 2',
        'value3' => 'Choice 3',
) );


add_action( 'customize_register', 'sci_customize_controls_init' );


Example and class for usage

You can see on my current theme, how it’s possible to use this. Also you can usage the class. See this class on Github an check the functions.php for include this.

Start & init

You can register your custom settings for the theme customizer via the customize_register hook:

add_action( 'customize_register', 'themedemo_customize' );
function themedemo_customize($wp_customize) {

    $wp_customize->add_section( 'themedemo_demo_settings', array(
        'title'          => 'Demonstration Stuff',
        'priority'       => 35,
    ) );

    $wp_customize->add_setting( 'some_setting', array(
        'default'        => 'default_value',
    ) );

    $wp_customize->add_control( 'some_setting', array(
        'label'   => 'Text Setting',
        'section' => 'themedemo_demo_settings',
        'type'    => 'text',
    ) );

    $wp_customize->add_setting( 'some_other_setting', array(
        'default'        => '#000000',
    ) );

    $wp_customize->add_control( new WP_Customize_Color_Control( $wp_customize, 'some_other_setting', array(
        'label'   => 'Color Setting',
        'section' => 'themedemo_demo_settings',
        'settings'   => 'some_other_setting',
    ) ) );


In-Theme usage:

Use it, like in the example below ↓:

echo 'some_setting => ' .get_theme_mod( 'some_setting', 'default_value' )."\n";
echo 'some_other_setting => ' .get_theme_mod( 'some_other_setting', '#000000' )."\n";
echo 'non_existent_setting => '.get_theme_mod( 'non_existent_setting', 'default_value' )."\n";


The you can also change the control:

$wp_customize->add_control( 'themename_color_scheme', array(
    'label'      => __( 'Color Scheme', 'themename' ),
    'section'    => 'themename_color_scheme',
    'settings'   => 'themename_theme_options[color_scheme]',
    'type'       => 'radio',
    'choices'    => array(
        'value1' => 'Choice 1',
        'value2' => 'Choice 2',
        'value3' => 'Choice 3',
) );

The default control-type is text. It creates a text box control. Another control-type is dropdown-pages, which creates a dropdown list of the WordPress Pages.

But that’s not all. There’re actually several more, but because they’re so custom, they’re declared differently.

This one makes use of OOP:

    new WP_Customize_Color_Control( $wp_customize, 'link_color', array(
        'label'    => __( 'Link Color', 'themename' ),
        'section'  => 'themename_color_scheme',
        'settings' => 'themename_theme_options[link_color]',
    ) )

Additional notes:

  • WP_Customize_Upload_Control – This gives you an upload box for files. However, you probably won’t use this directly,
    you’ll want to extend it for other things… like:
    This gives you the image picker and the uploader box. It extends the
    upload controller. You can see it in action on the custom background
    piece, where a user can upload a new file to be the background image.
  • WP_Customize_Header_Image_Control – Because of the resizing action of
    the header piece, it needs a bit of special handling and display, so
    the WP_Customize_Header_Image_Control extends the
  • WP_Customize_Image_Control to add that functionality. You can see it
    in action on the custom header piece, where a user can upload a new
    file to be the header image.

You can find more about “Theme Customizer” in ottos blog.

Update 11/06/2012

Live Example for read possibilities and more examples, see the open repo for the source and the doku.

Update 01/15/2013

We have create a repo on github with custom class to use it, easy and ready. Maybe you can only use it or advance with your ideas and solutions.

Leave a Comment