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. Rob

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' );
  • 3
    Minor point, but unless your control is going into the WordPress core, don't use the WP_ prefix. Use your own plugin/theme name as the prefix for the class name. – Otto Aug 3 '12 at 17:16

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: WP_Customize_Image_Control – 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.


Ok, here's how to do this. Seperate your control class(es) to one or more new files.

You have a function or method hooked on customize_register, right? In that function or method require once your new files just before adding your custom controls. Then PHP won't complain about redefining classes.

Note: This will not work out of the box, but shows the trick.

add_action('customize_register', array('myAddControl', 'customize_register') );

class myAddControl{
public function customize_register()
    global $wp_customize;

            //This will do the trick

    $wp_customize->add_section( 'gctfw_switch_theme' , array(
        'title'      => 'Switch theme',
        'priority'   => 25,
    ) );

    $wp_customize->add_setting( 'gctfw_select_theme' , array(
        'default'     => $wp_customize->theme()->get('Name'),
        'transport'   => 'refresh',
        'capabilities' => 'manage_options'
    ) );

    $myControl = new gctfw_Theme_Control( $wp_customize, 'gctfw_select_theme', array(
        'label'        => __( 'Select theme', 'mytheme' ),
        'section'    => 'gctfw_switch_theme',
        'settings'   => 'gctfw_select_theme',
    ) ) ;
    $wp_customize->add_control( $myControl );

You're never using your class. Try passing a new instance of your class to the add_control method:

$control_args = array(
  // your args here

$my_control = new WP_Customize_Palette_Control(
                $wp_customize, 'themename_color_scheme', $control_args);


Also, I don't think WP knows that the option name for your setting is part of an array. Maybe it's better to have themename_theme_options_color_scheme instead of themename_theme_options[color_scheme].

The class your extending belongs to the image upload control. If you're creating a color picker, you should probably extend the WP_Customize_Control class.


Just for completeness: An example on how to add a number field to the Theme Customizer.

class Customize_Number_Control extends WP_Customize_Control
    public $type = 'number';

    public function render_content()
            <span class="customize-control-title"><?php echo esc_html( $this->label ); ?></span>
            <input type="number" size="2" step="1" min="0" value="<?php echo esc_attr(  $this->value() ); ?>" />
  • I don't think that's necessary, you can just pass number as the type for default Control, and use input_attrs to pass step, etc. – Ian Dunn Jun 30 '15 at 21:21
  • @IanDunn May you want to add an example as additional answer? Thanks! – kaiser Jun 30 '15 at 22:08

I think you have to add backslash before the WP_Customize. So, it will be

class WP_Customize_Palette_Control extends \WP_Customize_Image_Control

, Because backslash assumed that the WP_Customize_Image_Control not from same Namespace

Let me know if it helped

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service, privacy policy and cookie policy

Not the answer you're looking for? Browse other questions tagged or ask your own question.