How to Get the Attachment ID of the WordPress Header Image

Skip to the answer

I saw a question on Twitter today about getting the attachment ID for the header image set through the WordPress theme customization screen. I haven’t worked with that part of the WordPress API before, so I wasn’t exactly sure how to do it. I decided to find out so I could help another developer and, maybe, save myself some leg work down the road.

I started by activating the 2013 theme on my local WordPress install. I knew this theme uses the header image functionality, and figured it was probably a good place to start looking. After activating the theme, I uploaded a custom header image and inspected the frontend of the site with Chrome’s web inspector to see what kind of markup and styles are used to place the image in the header.

I was able to see the background image was set on an element with the class site-header. I did a text search on my local WordPress install and found a file inside the 2013 theme called custom-header.php (an obviously promising name). I perused that file and found a call to the function get_header_image. At this point, I knew I was getting close.

There were a couple of layers of abstraction, but I eventually found the get_theme_mods functionality. I threw the following line into my functions.php file so I could see what was returned from the function.

error_log(print_r(get_theme_mods(), true));

As a side note, I find this to be a simple and effective method of exploring the WordPress API. I noticed the data returned contained a key called header_image_data. The value for that key contained the information I needed, so it was just time to walk back up the hierarchy and figure out the best way to get the data. get_theme_mod delegates to get_theme_mods so I knew I had my answer.

All you have to do to get the attachment ID of the uploaded header image is call get_theme_mod('header_image_data'), check the result is an array, and that the attachment_id key is set. If it is, that’s your answer.

$data = get_theme_mod('header_image_data');

$attachment_id = is_array($data) && isset($data['attachment_id']) ? $data['attachment_id'] : false;

if($attachment_id) {
	// Do something here

5 thoughts on “How to Get the Attachment ID of the WordPress Header Image

    1. Louis

      Ok I found the answer that no one has on the net I been looking for days now.

      Here is how I was able to do it. Hope this helps someone out there

      // This is getting the image / url
      $feature1 = get_theme_mod(‘feature_image_1’);

      // This is getting the post id
      $feature1_id = attachment_url_to_postid($feature1);

      // This is getting the alt text from the image that is set in the media area
      $image1_alt = get_post_meta( $feature1_id, ‘_wp_attachment_image_alt’, true );


      <a href="”><img class="img-responsive center-block" src="” alt=””>

  1. Fabian

    I was looking for something like this… but it dosn’t seem to work anymore? The $attachement_id ist empty/false even when an Header is set…Anyone else who tried this? Thanks anyway :)

  2. Fabian

    This is the new correct first line of code: $data = get_object_vars(get_theme_mod(‘header_image_data’));
    Since the header image data is an object and not an array (anymore?) you have to use get_object_vars


Leave a Reply

Your email address will not be published. Required fields are marked *