Using WordPress ‘add_custom_image_header()’ PHP function

by

The add_custom_image_header() WordPress PHP function is used to add callbacks for image header display. This function is called on the ‘wp_head’ action and on the custom header administration screen. It can optionally output a custom header image div on the custom header administration screen.

Usage

add_custom_image_header($wp_head_callback, $admin_head_callback, $admin_preview_callback);

For instance, if you have three functions, display_header(), admin_header() and admin_preview(), you can use add_custom_image_header() like this:

add_custom_image_header('display_header', 'admin_header', 'admin_preview');

Parameters

  • $wp_head_callback (callable) – This required parameter is a callback function that is invoked on the ‘wp_head’ action.
  • $admin_head_callback (callable) – This required parameter is a callback function that is called on the custom header administration screen.
  • $admin_preview_callback (callable) – This optional parameter is a callback function that outputs a custom header image div on the custom header administration screen. If not provided, its default value is ” (an empty string).

More information

See WordPress Developer Resources: add_custom_image_header()

Examples

Basic Usage

This is how you might typically use the add_custom_image_header() function. This code will call the display_header(), admin_header(), and admin_preview() functions at the appropriate times.

function display_header() {
    // Display the custom header image.
    echo '<img src="' . get_header_image() . '" />';
}

function admin_header() {
    // Admin header code goes here.
}

function admin_preview() {
    // Admin preview code goes here.
}

// Add the custom image header callbacks.
add_custom_image_header('display_header', 'admin_header', 'admin_preview');

Omitting the Optional Parameter

You can also call add_custom_image_header() without the optional $admin_preview_callback parameter. If you do this, it will only use the display_header() and admin_header() functions.

function display_header() {
    // Display the custom header image.
    echo '<img src="' . get_header_image() . '" />';
}

function admin_header() {
    // Admin header code goes here.
}

// Add the custom image header callbacks without admin preview.
add_custom_image_header('display_header', 'admin_header');

Using Lambda Functions

You can use lambda functions as the callback functions in add_custom_image_header().

add_custom_image_header(
    function() { /* wp_head action code */ },
    function() { /* admin head code */ },
    function() { /* admin preview code */ }
);

Using Class Methods

If the callback functions are methods in a class, you can provide the class instance and method name as an array.

class HeaderClass {
    function display_header() { /* Display header code */ }
    function admin_header() { /* Admin header code */ }
    function admin_preview() { /* Admin preview code */ }
}

$instance = new HeaderClass();

add_custom_image_header([$instance, 'display_header'], [$instance, 'admin_header'], [$instance, 'admin_preview']);