Function and usage of add_custom_image_header() in wordpress


Answers ( 1 )


    The add_custom_image_header() function in WordPress is used to add callbacks for the display and management of a custom header image within a theme. This function is part of the WordPress theme customization API, which allows theme developers to provide options for users to customize their theme's appearance.

    Here's a detailed explanation of the function and its parameters:


    add_custom_image_header( callable $wp_head_callback, callable $admin_head_callback, callable $admin_preview_callback = '' )


    • Purpose: The function is used to add callbacks that handle the display and administration of custom header images in a WordPress theme.
    • Use Case: Typically used in a theme's functions.php file to allow users to customize the header image of their theme through the WordPress Customizer or the theme administration panel.
    • See Also: The add_theme_support() function, which is used to declare support for certain features in a WordPress theme, including custom headers.


    1. $wp_head_callback (callable, required)

      • Purpose: This callback is executed on the 'wp_head' action hook. It's responsible for the front-end display of the custom header image.
      • Example Usage: Often used to output inline CSS that sets the header image as a background for a page element.
    2. $admin_head_callback (callable, required)

      • Purpose: This callback is called on the custom header administration screen within the WordPress admin area. It's used for adding any necessary CSS or JavaScript for the admin header screen.
      • Example Usage: Could be used to style the preview of the custom header in the WordPress admin.
    3. $admin_preview_callback (callable, optional, default: '')

      • Purpose: Outputs a custom header image div on the custom header administration screen. This is an optional parameter.
      • Example Usage: Could be used to display a live preview of the header image as it would appear on the front end.

    Sample Usage:

    Here's a basic example of how add_custom_image_header() might be used in a theme's functions.php file:

    function my_theme_custom_header_setup() {
        // Front-end display callback
        function my_header_style() {
            <style type="text/css">
                .header-image {
                    background-image: url(<?php header_image(); ?>);
                    /* Additional styling */
        // Admin panel display callback
        function my_admin_header_style() {
            <style type="text/css">
                /* Admin panel styling for header image */
        // Admin preview callback (optional)
        function my_admin_header_image() {
            <div class="header-preview" style="background-image: url(<?php header_image(); ?>);">
                <!-- Preview content -->
        add_custom_image_header('my_header_style', 'my_admin_header_style', 'my_admin_header_image');
    add_action( 'after_setup_theme', 'my_theme_custom_header_setup' );

    In this example, my_header_style() is the callback for displaying the header image on the front end, my_admin_header_style() is for styling the header image in the admin panel, and my_admin_header_image() is for displaying a live preview of the header image in the admin panel. The add_custom_image_header() function ties these callbacks to the appropriate actions within WordPress.

Leave an answer