In the Header Image panel, there is a description that says:

Click “Add new image” to upload an image file from your computer. Your theme works best with an image with a header size of 1200 × 280 pixels — you’ll be able to crop your image once you upload it for a perfect fit.

I'm trying to change this text with this:

$wp_customize->get_control( 'header_image' )->description = 'New text here';

But its not working. Am I missing something here?

2 Answers 2


The description param unfortunately is not used in this control. You can see that the message is hard-coded in the control's template. That should be changed in core, but in the mean time, you can enqueue some JS at the customize_controls_enqueue_scripts action with the dependency of customize-controls which does this:

wp.customize.control( 'header_image', function( control ) {
    control.deferred.embedded.done( function() {
        var el = control.container.find( '.customize-control-description' );
        el.html( control.params.description );
    } );
} );

This JS will continue to work if the control's description param starts to be used in core in a future release.

function change_header_image_desc( $translated_text ) {
    if ( $translated_text == 'While you can crop images to your liking after clicking <strong>Add new image</strong>, your theme recommends a header size of %s pixels.' ) {
        $translated_text = 'New Description here';
    return $translated_text;
add_filter( 'gettext', 'change_header_image_desc', 20 );

This is case-sensitive so type it exactly as you see it on your WordPress Theme.

  • unfortunately this doesn't work. Do you know if there's a way to do it inside customize_register like all other controls? Nov 18, 2017 at 11:32
  • this is actual file which is generating that text [ wp-includes\customize\class-wp-customize-header-image-control.php] copy the text from this file and paste into function like i did.
    – Lovin Nagi
    Nov 18, 2017 at 11:35

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service and acknowledge you have read our privacy policy.

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