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!