Has anyone seen a way to add a new header_image to a theme? I need to add two configurable images in a theme. It doesn't really matter if it gets added as a new "Header" admin theme menu or if it's added to the existing Apperance->Header menu.

I'm a bit new to plugin development so any help in the right direction is appreciated. I can't really find any hooks or actions to attach to.

Similar to this request

2 Answers 2


See TwentyEleven to get the idea: it uses register_default_headers() to add new header images. In your plugin or theme just add:

add_action( 'after_setup_theme', 'wpse_42529_add_header_images' );

function wpse_42529_add_header_images()
            'a_short_name' => array(
            'url' => '%s/images/headers/a_short_name.jpg',
            'thumbnail_url' => '%s/images/headers/a_short_name-thumbnail.jpg',
            'description' => __( 'Wheel', 'twentyeleven' )
        'another_image' => array(
            'url' => '%s/images/headers/another_image.jpg',
            'thumbnail_url' => '%s/images/headers/another_image-thumbnail.jpg',
            'description' => __( 'Shore', 'twentyeleven' )

The %s will be replaced by the stylesheet directory URI. You don't have to use that. You can use plugin_dir_url( __FILE__ ) instead of %s.

You can call register_default_headers() multiple times, it works just like a add_default_headers().


To add a new page for custom images similar to the custom header you should extend the class Custom_Image_Header in a theme options page. But this very class is under reconstruction right now – it is almost impossible to write future proof code based on this. I would wait for WordPress 3.4 and build the code on a more stable base.
Well … I will do that, because I need it probably too.

Another way: copy and modify the current class instead of extending it.

  • I think you have misunderstood what I'm asking for. I'm not talking about different images, but two images containers.
    – grm
    Feb 16, 2012 at 12:26
  • @grm I added a note to explain why I would wait for WP 3.4. Sorry for misinterpreting your question.
    – fuxia
    Feb 17, 2012 at 6:23
  • Do you need a thumbnail url? How would I go about making one?
    – AlxVallejo
    Aug 9, 2012 at 15:38

This has already been answered here before:

If you look at the Twenty Eleven theme and other default themes you can use the featured image as a custom header image if its exactly the same width as the default header.

        // Check to see if the header image has been removed
        $header_image = get_header_image();
        if ( $header_image ) :
            // Compatibility with versions of WordPress prior to 3.4.
            if ( function_exists( 'get_custom_header' ) ) {
                 * We need to figure out what the minimum width should be for our featured image.
                 * This result would be the suggested width if the theme were to implement flexible widths.
                $header_image_width = get_theme_support( 'custom-header', 'width' );
            } else {
                $header_image_width = HEADER_IMAGE_WIDTH;
    <a href="<?php echo esc_url( home_url( '/' ) ); ?>">
             * The header image.
             * Check if this is a post or page, if it has a thumbnail, and if it's a big one
            if ( is_singular() && has_post_thumbnail( $post->ID ) &&
                    ( /* $src, $width, $height */ $image = wp_get_attachment_image_src( get_post_thumbnail_id( $post->ID ), array( $header_image_width, $header_image_width ) ) ) &&
                    $image[1] >= $header_image_width ) :
                // Houston, we have a new header image!
                echo get_the_post_thumbnail( $post->ID, 'post-thumbnail' );
            else :
                // Compatibility with versions of WordPress prior to 3.4.
                if ( function_exists( 'get_custom_header' ) ) {
                    $header_image_width  = get_custom_header()->width;
                    $header_image_height = get_custom_header()->height;
                } else {
                    $header_image_width  = HEADER_IMAGE_WIDTH;
                    $header_image_height = HEADER_IMAGE_HEIGHT;
            <img src="<?php header_image(); ?>" width="<?php echo $header_image_width; ?>" height="<?php echo $header_image_height; ?>" alt="" />
        <?php endif; // end check for featured image or standard header ?>
    <?php endif; // end check for removed header image ?>

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.