Using WordPress ‘get_header_image_tag’ PHP filter

by

The get_header_image_tag WordPress PHP filter allows you to modify the markup of header images.

Usage

add_filter( 'get_header_image_tag', 'your_custom_function', 10, 3 );

function your_custom_function( $html, $header, $attr ) {
    // your custom code here

    return $html;
}

Parameters

  • $html (string): The HTML image tag markup being filtered.
  • $header (object): The custom header object returned by get_custom_header().
  • $attr (array): Array of the attributes for the image tag.

More information

See WordPress Developer Resources: get_header_image_tag

Examples

Add a CSS class to the header image

Add a custom CSS class to the header image for styling purposes.

add_filter( 'get_header_image_tag', 'add_custom_header_class', 10, 3 );

function add_custom_header_class( $html, $header, $attr ) {
    $attr['class'] .= ' custom-header-class';
    $html = '<img ' . join( ' ', array_map( function( $key, $value ) {
        return $key . '="' . esc_attr( $value ) . '"';
    }, array_keys( $attr ), $attr ) ) . ' />';

    return $html;
}

Add a data attribute to the header image

Add a data-custom attribute to the header image for JavaScript usage.

add_filter( 'get_header_image_tag', 'add_custom_header_data_attribute', 10, 3 );

function add_custom_header_data_attribute( $html, $header, $attr ) {
    $attr['data-custom'] = 'my-custom-data';
    $html = '<img ' . join( ' ', array_map( function( $key, $value ) {
        return $key . '="' . esc_attr( $value ) . '"';
    }, array_keys( $attr ), $attr ) ) . ' />';

    return $html;
}

Change the header image alt attribute

Modify the alt attribute of the header image.

add_filter( 'get_header_image_tag', 'change_header_image_alt', 10, 3 );

function change_header_image_alt( $html, $header, $attr ) {
    $attr['alt'] = 'Custom alt text for header image';
    $html = '<img ' . join( ' ', array_map( function( $key, $value ) {
        return $key . '="' . esc_attr( $value ) . '"';
    }, array_keys( $attr ), $attr ) ) . ' />';

    return $html;
}

Set a maximum width for the header image

Limit the header image width to a maximum value.

add_filter( 'get_header_image_tag', 'limit_header_image_width', 10, 3 );

function limit_header_image_width( $html, $header, $attr ) {
    $attr['style'] = 'max-width: 1200px;';
    $html = '<img ' . join( ' ', array_map( function( $key, $value ) {
        return $key . '="' . esc_attr( $value ) . '"';
    }, array_keys( $attr ), $attr ) ) . ' />';

    return $html;
}

Add an ID to the header image

Add an ID attribute to the header image for easier targeting.

add_filter( 'get_header_image_tag', 'add_header_image_id', 10, 3 );
function add_header_image_id( $html, $header, $attr ) {
    $attr['id'] = 'custom-header-image-id';
    $html = '<img ' . join( ' ', array_map( function( $key, $value ) { return $key . '="' . esc_attr( $value ) . '"'; }, array_keys( $attr ), $attr ) ) . ' />';
    return $html;
}