Flexible headers in WordPress 3.4 themes

As of WordPress 3.4 Beta1, theme authors can allow custom header images with flexible heights, widths, or both.

In other words, instead of being limited to a fixed size determined by the designer, as you’re already familiar with:

With flexible headers, you can allow users to upload smaller or larger headers without having to make a child theme or (worse) hack your theme, like so:

How to do it:

Image header support in 3.4 no longer uses all the constants that had to be defined in previous versions — HEADER_IMAGE_HEIGHT, HEADER_IMAGE_WIDTH, HEADER_TEXT_COLOR and the like are now gone. Instead, all the header support options are included in a single array, and enabled with a call to add_theme_support() in your theme’s functions.php file.

This is how the array looks in the theme I used for the screenshots above:

// Add support for flexible headers
 $header_args = array(
 'flex-height' => true,
 'height' => 200,
 'flex-width' => true,
 'width' => 950,
 'default-image' => '%s/images/headers/path.jpg',
 'admin-head-callback' => 'mytheme_admin_header_style',

 add_theme_support( 'custom-header', $header_args );

If flex-height or flex-width are not included in the array, height and width will be fixed sizes, replacing the old HEADER_IMAGE_HEIGHT and HEADER_IMAGE_WIDTH. If flex-height and flex-width are included, height and width will be used as suggested dimensions instead.

Don’t forget to remove any references to the old constants in your template files — in my header.php, I simply replaced.

<img src="<?php header_image(); ?>" width="<?php echo HEADER_IMAGE_WIDTH; ?>" height="<?php echo HEADER_IMAGE_HEIGHT; ?>" alt="" />


<img src="<?php header_image(); ?>" height="<?php echo get_custom_header()->height; ?>" width="<?php echo get_custom_header()->width; ?>" alt="" />

For reference, here’s the full set of options and their default values, as found in /wp-includes/theme.php. Note that the other header image options like text, text color, and randomization are available in the same add_theme_support() call by setting only the options you need:

$defaults = array(
'default-image' => '',
'random-default' => false,
'width' => 0,
'height' => 0,
'flex-height' => false,
'flex-width' => false,
'default-text-color' => '',
'header-text' => true,
'uploads' => true,
'wp-head-callback' => '',
'admin-head-callback' => '',
'admin-preview-callback' => '',

A few important notes:

  • Flexible header support has to be built into each theme – it will not work automatically with your pre-existing themes.
  • This functionality requires WordPress 3.4, which is currently in beta. You can grab the latest here (.zip file). Please use it for testing and development, but don’t run it in production unless you know what you’re doing and have some risk tolerance.
  • Design-wise, flexible heights are relatively easy; flexible widths are much trickier to work into a layout while still looking good. Experiment!

31 thoughts on “Flexible headers in WordPress 3.4 themes

  1. Thank you for this article!

    To get width and height, you can use get_theme_support( 'custom-header', 'width' ); or get_custom_header()->width;. (I think :) )

  2. Quite right – I’d just left them out of the header to make it easier to test, but I’m adding your suggestion to the post now. Thanks!

    Actually, no — the get_theme_support() call replaces the header with the default height set in the array, not the actual value of the current image. Best to leave it out in the header.php case. It’s available any time you need to get the suggested value (for instance, we use that value on the Custom Header page in the admin.

    • On get_custom_header()->width, too? That’s odd.
      Refering to the code (without actually testing it), I thougth the values of the current image would override the defaults.

      Hm, maybe I should start testing then. :)

      • Hmmm, I’m not sure about get_custom_header()->width off the top of my head. Please let me know what you figure out if you have a chance to test, and I’ll do the same. And thanks for the questions!

        EDIT: Yes, get_custom_header()->width works as expected. Thanks again for the feedback, and I’ll add it to the post.

  3. Pingback: Updating Custom Backgrounds and Custom Headers for WordPress 3.4 « Make WordPress Themes

  4. What if i need two different header sizes – one for homepage, second for all others. Is there any easy way how to do it (other way then simply manual/css)

    • There’s no automatic way to do what you describe — you’ll still have to test for is_front_page() and output the header you want according to whether you’re on the home page or some other location.

  5. Pingback: WordPress 3.4 RC2 - { EyesX } Mattias Tengblad Online

  6. Pingback: http://sabreuse.com/flexible-headers-in-wordpress-3-4-themes/ - Dougal Campbell's geek ramblings

  7. Pingback: Get Closer to Wordpress 3.4 - Kharis Sulistiyono

  8. Unfortunately this doesn’t work for me at all. I’m running 3.4 RC2, and I don’t get any option for customizing the header, neither in the customize-panel, nor anywhere in the menu.

    • I’m sorry to hear it’s not working for you – would you mind posting your functions.php and header.php to a pastebin?

  9. Pingback: ❶ Připravte se na WordPress 3.4 ✔ SEO Konzultant

  10. Pingback: WordPress 3.4 Field Guide for Developers « WordPress Development Updates

  11. Pingback: WordPress 3.4 out and running | Anthalis Central

  12. Pingback: What’s New in WordPress 3.4@smashing | seo博客大全

  13. Is there any way to make this appear in a theme’s option page, rather than as a separate item in the Admin menu?

  14. Pingback: What’s New in WordPress 3.4 « Louis Gia Nguyen

  15. Pingback: What’s New in WordPress 3.4 | MyOfflineTheme.com Skyrocket Your Offline Business Just Now

  16. Pingback: What’s New in WordPress 3.4 | DigitalMofo

  17. Pingback: What’s New in WordPress 3.4 » E BLADE

  18. Pingback: Upgrade WordPress to 3.4, Features | WordPress Webmaster

  19. Pingback: What’s New in WordPress 3.4 | Web Design Kingston

  20. Pingback: WordPress 3.4′ün Yenilikleri | Smashing Magazine Türkiye

  21. Pingback: What’s New in WordPress 3.4 | CS5 Design

  22. Pingback: What’s New in WordPress 3.4 | Steve deGuzman

  23. Pingback: WordPress 3.4 Is Coming Soon! Find Out What to Expect • Gr8WhiteNorth

  24. Pingback: What’s New in WordPress 3.4 | Buypappa blog

Comments are closed.