The custom header allows the site administrator to customize the site’s header image. This provides WordPress users with more flexibility and control over the appearance of their websites. The image can also be customized and cropped using the visual editor, which is found in Appearance > Header or Appearance > Customize > Header Image section of the admin interface. The custom header feature is the functionality relevant only to the Classic Theme.
The support for custom header must be added with add_theme_support( 'custom-header', $args ) in the functions.php file. The second parameter, $args, is an array of additional arguments used to configure the custom header’s features. The add_theme_support() function should be called within a function hooked to the after_setup_theme action.
Default Arguments of Custom Header
The configuration options available in the $args argument array passed to the add_theme_support() function support the following values.
$args = array(
// Default Header Image to display.
'default-image' => get_template_directory_uri() . '/images/headers/default.jpg',
// Display the header text along with the image.
'header-text' => false,
// Header text color default.
'default-text-color' => '000',
// Header image width (in pixels).
'width' => 1000,
// Header image height (in pixels).
'height' => 198,
// Header image random rotation default.
'random-default' => false,
// Enable upload of image file in admin.
'uploads' => false,
// Function to be called in theme head section.
'wp-head-callback' => 'wphead_cb',
// Function to be called in preview page head section.
'admin-head-callback' => 'adminhead_cb',
// Function to produce preview markup in the admin screen.
'admin-preview-callback' => 'adminpreview_cb',
);
Making the Custom Header Flexible
You can configure several other options for the custom header using the second argument array, $args, of the add_theme_support() function. The argument array accepts the boolean flex-width and flex-height options. Placing these options in an argument array with a boolean value of true makes the custom header flexible. In the other cases, either setting these options to false or omitting them results in the fixed-sized header image.
Setting the Default Header Images
You can also configure the default header images for users to choose from in the customizer, located at Appearance > Header admin screen, so that users can select any available image when the theme is activated for the first time. For this, you need to register the default images using the register_default_headers() WordPress function that accepts an array of image data. Additionally, this function enables WordPress users to set the default header image as the custom header by allowing them to modify the records in the theme_mod_{theme_name} option.
Displaying the Header Image on the Front End
On the front-end of WordPress, site users need to check whether the custom header is supported using the has_header_image() or has_custom_header() functions. Alternatively, get_header_image() returns the header image URL if a custom header is available; otherwise, it returns false on failure. Additionally, header_image() prints the URL of the header image. The only difference between these two functions is that the former returns the URL, whereas the latter prints it. Furthermore, the get_custom_header() function returns an object containing header image data, including properties such as url, thumbnail_url, width, height, video, and attachment_id.
Quirk Like Behavor of Custom Header
The default custom header image is not saved when the default image is chosen and the publish button is clicked. This is the quirk-like, but intentional and expected, behavior in WordPress for handling the default custom header image. This is because WordPress uses the default header image (set with the default-image option) if no header image is selected. Therefore, when selecting and publishing the default image, it does not work because this action does not create any database option in the theme_mod_{theme_name} option. When publishing the default header image, WordPress treats it as the default and does not create a database option; thus, this appears to be a quirk.
The issue mainly occurs when you remove all previously selected custom headers from the media gallery and then try to set the default header image again. The ultimate result is that the default header does not stick in the Customizer preview and does not appear on the website’s front end. Please do these three measures to avoid this problem.
- Upload a new header image and set it again as a custom header image.
- You need to carefully remove the
header_image configuration from the theme_mod_{theme_name} option.
- Register the default header image with
register_default_headers() so WordPress recognizes it as the official choice for the custom header.
// Register the default header properly so WordPress can save it when selected.
register_default_headers( array(
'topicbin-default' => array(
'url' => get_template_directory_uri() . '/assets/src/images/topicbin.png',
'thumbnail_url' => get_template_directory_uri() . '/assets/src/images/topicbin.png',
'description' => __( 'Default Header', 'topicbin' ),
),
) );
With this code in place, WordPress treats your default image as a selectable header image and saves it properly when the user selects it and clicks Publish. Usage of the register_default_headers() function should now create a header_image record in the theme_mods_{theme_name} option in your database. Accordingly, the intended custom header image should now appear in the Customizer preview and on the front end. The Customizer API for WordPress Theme Settings article offers a practical understanding of the Customizer API and its application to theme modifications in WordPress.
Header Text and Color Options
Setting the value of header-text equal to true enables the “Display Site Title and Tagline” checkbox in Customizer. You can use the display_header_text() function to determine whether the header text and tagline should be displayed or not. This function returns the Boolean value of either true or false. Similarly, the default-text-color value gives the settings option named “Header Text Color” in the Customizer, provided that the “Display Site Title and Tagline” option is checked, and lets to set the default value for header text color. This customizer option allows you to easily customize the header text color, which you can get by using the get_header_textcolor() function.
The header-text and default-text-color options do not work independently; they only enable the option in the Customizer. You should apply those header text and color options on your own in the theme.
Final Remarks
The complete code for setting the custom header will be the following:
function topicbin_theme_setup() {
// Custom header.
$args = array(
'default-image' => get_template_directory_uri() . '/assets/src/images/topicbin.png',
'default-text-color' => '000',
'width' => 490,
'height' => 150,
'flex-width' => true,
'flex-height' => false,
);
add_theme_support( 'custom-header', $args );
// Register the default header properly so WordPress can save it when selected.
register_default_headers(
array(
'topicbin-default' => array(
'url' => get_template_directory_uri() . '/assets/src/images/topicbin.png',
'thumbnail_url' => get_template_directory_uri() . '/assets/src/images/topicbin.png',
'description' => __( 'Default Header', 'topicbin' ),
),
)
);
}
add_action( 'after_setup_theme', 'topicbin_theme_setup' );
You can integrate this code into your theme’s functions.php file or the main PHP file of your plugin to get the custom header working. For more details on the documents required for the custom header, please refer to the official theme developer handbook.