Title: get_header_image_tag
Published: December 9, 2015
Last modified: February 24, 2026

---

# get_header_image_tag( array $attr = array() ): string

## In this article

 * [Parameters](https://developer.wordpress.org/reference/functions/get_header_image_tag/?output_format=md#parameters)
 * [Return](https://developer.wordpress.org/reference/functions/get_header_image_tag/?output_format=md#return)
 * [Source](https://developer.wordpress.org/reference/functions/get_header_image_tag/?output_format=md#source)
 * [Hooks](https://developer.wordpress.org/reference/functions/get_header_image_tag/?output_format=md#hooks)
 * [Related](https://developer.wordpress.org/reference/functions/get_header_image_tag/?output_format=md#related)
 * [Changelog](https://developer.wordpress.org/reference/functions/get_header_image_tag/?output_format=md#changelog)

[ Back to top](https://developer.wordpress.org/reference/functions/get_header_image_tag/?output_format=md#wp--skip-link--target)

Creates image tag markup for a custom header image.

## 󠀁[Parameters](https://developer.wordpress.org/reference/functions/get_header_image_tag/?output_format=md#parameters)󠁿

 `$attr`arrayoptional

Additional attributes for the image tag. Can be used to override the default attributes.

Default:`array()`

## 󠀁[Return](https://developer.wordpress.org/reference/functions/get_header_image_tag/?output_format=md#return)󠁿

 string HTML image element markup or empty string on failure.

## 󠀁[Source](https://developer.wordpress.org/reference/functions/get_header_image_tag/?output_format=md#source)󠁿

    ```php
    function get_header_image_tag( $attr = array() ) {
    	$header      = get_custom_header();
    	$header->url = get_header_image();

    	if ( ! $header->url ) {
    		return '';
    	}

    	$width  = absint( $header->width );
    	$height = absint( $header->height );
    	$alt    = '';

    	// Use alternative text assigned to the image, if available. Otherwise, leave it empty.
    	if ( ! empty( $header->attachment_id ) ) {
    		$image_alt = get_post_meta( $header->attachment_id, '_wp_attachment_image_alt', true );

    		if ( is_string( $image_alt ) ) {
    			$alt = $image_alt;
    		}
    	}

    	$attr = wp_parse_args(
    		$attr,
    		array(
    			'src'    => $header->url,
    			'width'  => $width,
    			'height' => $height,
    			'alt'    => $alt,
    		)
    	);

    	// Generate 'srcset' and 'sizes' if not already present.
    	if ( empty( $attr['srcset'] ) && ! empty( $header->attachment_id ) ) {
    		$image_meta = get_post_meta( $header->attachment_id, '_wp_attachment_metadata', true );
    		$size_array = array( $width, $height );

    		if ( is_array( $image_meta ) ) {
    			$srcset = wp_calculate_image_srcset( $size_array, $header->url, $image_meta, $header->attachment_id );

    			if ( ! empty( $attr['sizes'] ) ) {
    				$sizes = $attr['sizes'];
    			} else {
    				$sizes = wp_calculate_image_sizes( $size_array, $header->url, $image_meta, $header->attachment_id );
    			}

    			if ( $srcset && $sizes ) {
    				$attr['srcset'] = $srcset;
    				$attr['sizes']  = $sizes;
    			}
    		}
    	}

    	$attr = array_merge(
    		$attr,
    		wp_get_loading_optimization_attributes( 'img', $attr, 'get_header_image_tag' )
    	);

    	/*
    	 * If the default value of `lazy` for the `loading` attribute is overridden
    	 * to omit the attribute for this image, ensure it is not included.
    	 */
    	if ( isset( $attr['loading'] ) && ! $attr['loading'] ) {
    		unset( $attr['loading'] );
    	}

    	// If the `fetchpriority` attribute is overridden and set to false or an empty string.
    	if ( isset( $attr['fetchpriority'] ) && ! $attr['fetchpriority'] ) {
    		unset( $attr['fetchpriority'] );
    	}

    	// If the `decoding` attribute is overridden and set to false or an empty string.
    	if ( isset( $attr['decoding'] ) && ! $attr['decoding'] ) {
    		unset( $attr['decoding'] );
    	}

    	/**
    	 * Filters the list of header image attributes.
    	 *
    	 * @since 5.9.0
    	 *
    	 * @param array  $attr   Array of the attributes for the image tag.
    	 * @param object $header The custom header object returned by 'get_custom_header()'.
    	 */
    	$attr = apply_filters( 'get_header_image_tag_attributes', $attr, $header );

    	$attr = array_map( 'esc_attr', $attr );
    	$html = '<img';

    	foreach ( $attr as $name => $value ) {
    		$html .= ' ' . $name . '="' . $value . '"';
    	}

    	$html .= ' />';

    	/**
    	 * Filters the markup of header images.
    	 *
    	 * @since 4.4.0
    	 *
    	 * @param string $html   The HTML image tag markup being filtered.
    	 * @param object $header The custom header object returned by 'get_custom_header()'.
    	 * @param array  $attr   Array of the attributes for the image tag.
    	 */
    	return apply_filters( 'get_header_image_tag', $html, $header, $attr );
    }
    ```

[View all references](https://developer.wordpress.org/reference/files/wp-includes/theme.php/)
[View on Trac](https://core.trac.wordpress.org/browser/tags/6.9.4/src/wp-includes/theme.php#L1270)
[View on GitHub](https://github.com/WordPress/wordpress-develop/blob/6.9.4/src/wp-includes/theme.php#L1270-L1374)

## 󠀁[Hooks](https://developer.wordpress.org/reference/functions/get_header_image_tag/?output_format=md#hooks)󠁿

 [apply_filters( ‘get_header_image_tag’, string $html, object $header, array $attr )](https://developer.wordpress.org/reference/hooks/get_header_image_tag/)

Filters the markup of header images.

 [apply_filters( ‘get_header_image_tag_attributes’, array $attr, object $header )](https://developer.wordpress.org/reference/hooks/get_header_image_tag_attributes/)

Filters the list of header image attributes.

## 󠀁[Related](https://developer.wordpress.org/reference/functions/get_header_image_tag/?output_format=md#related)󠁿

| Uses | Description | 
| [wp_get_loading_optimization_attributes()](https://developer.wordpress.org/reference/functions/wp_get_loading_optimization_attributes/)`wp-includes/media.php` |

Gets loading optimization attributes.

  | 
| [wp_calculate_image_srcset()](https://developer.wordpress.org/reference/functions/wp_calculate_image_srcset/)`wp-includes/media.php` |

A helper function to calculate the image sources to include in a ‘srcset’ attribute.

  | 
| [wp_calculate_image_sizes()](https://developer.wordpress.org/reference/functions/wp_calculate_image_sizes/)`wp-includes/media.php` |

Creates a ‘sizes’ attribute value for an image.

  | 
| [get_custom_header()](https://developer.wordpress.org/reference/functions/get_custom_header/)`wp-includes/theme.php` |

Gets the header image data.

  | 
| [get_header_image()](https://developer.wordpress.org/reference/functions/get_header_image/)`wp-includes/theme.php` |

Retrieves header image for custom header.

  | 
| [absint()](https://developer.wordpress.org/reference/functions/absint/)`wp-includes/load.php` |

Converts a value to non-negative integer.

  | 
| [wp_parse_args()](https://developer.wordpress.org/reference/functions/wp_parse_args/)`wp-includes/functions.php` |

Merges user defined arguments into defaults array.

  | 
| [apply_filters()](https://developer.wordpress.org/reference/functions/apply_filters/)`wp-includes/plugin.php` |

Calls the callback functions that have been added to a filter hook.

  | 
| [get_post_meta()](https://developer.wordpress.org/reference/functions/get_post_meta/)`wp-includes/post.php` |

Retrieves a post meta field for the given post ID.

  |

[Show 4 more](https://developer.wordpress.org/reference/functions/get_header_image_tag/?output_format=md#)
[Show less](https://developer.wordpress.org/reference/functions/get_header_image_tag/?output_format=md#)

| Used by | Description | 
| [get_custom_header_markup()](https://developer.wordpress.org/reference/functions/get_custom_header_markup/)`wp-includes/theme.php` |

Retrieves the markup for a custom header.

  | 
| [the_header_image_tag()](https://developer.wordpress.org/reference/functions/the_header_image_tag/)`wp-includes/theme.php` |

Displays the image markup for a custom header image.

  |

## 󠀁[Changelog](https://developer.wordpress.org/reference/functions/get_header_image_tag/?output_format=md#changelog)󠁿

| Version | Description | 
| [4.4.0](https://developer.wordpress.org/reference/since/4.4.0/) | Introduced. |

## User Contributed Notes

You must [log in](https://login.wordpress.org/?redirect_to=https%3A%2F%2Fdeveloper.wordpress.org%2Freference%2Ffunctions%2Fget_header_image_tag%2F)
before being able to contribute a note or feedback.