Using WordPress ‘get_uploaded_header_images()’ PHP function

The get_uploaded_header_images() WordPress PHP function retrieves the header images uploaded for the active theme.

Usage

To use the function, simply call it and assign the returned array to a variable:

$uploaded_header_images = get_uploaded_header_images();

Parameters

This function has no parameters.

More information

See WordPress Developer Resources: get_uploaded_header_images

Examples

Displaying the list of uploaded header images

Display all uploaded header images for the active theme with their respective URLs:

$uploaded_header_images = get_uploaded_header_images();
if (!empty($uploaded_header_images)) {
  echo '<ul>';
  foreach ($uploaded_header_images as $image) {
    echo '<li><img src="' . esc_url($image['url']) . '" alt="Header image" /></li>';
  }
  echo '</ul>';
} else {
  echo 'No header images found.';
}

Displaying a random uploaded header image

Select and display a random header image from the uploaded images for the active theme:

$uploaded_header_images = get_uploaded_header_images();
if (!empty($uploaded_header_images)) {
  $random_image = array_rand($uploaded_header_images);
  echo '<img src="' . esc_url($uploaded_header_images[$random_image]['url']) . '" alt="Random header image" />';
} else {
  echo 'No header images found.';
}

Displaying the number of uploaded header images

Count and display the number of uploaded header images for the active theme:

$uploaded_header_images = get_uploaded_header_images();
$count = count($uploaded_header_images);
echo 'There are ' . $count . ' uploaded header images.';

Checking if a specific header image is uploaded

Check if a header image with a specific file name is uploaded for the active theme:

$uploaded_header_images = get_uploaded_header_images();
$specific_image = 'header-image.jpg';
$found = false;

foreach ($uploaded_header_images as $image) {
  if (basename($image['url']) === $specific_image) {
    $found = true;
    break;
  }
}

if ($found) {
  echo 'The specific header image is uploaded.';
} else {
  echo 'The specific header image is not uploaded.';
}

Removing a specific uploaded header image

Remove a specific header image from the uploaded images for the active theme:

function remove_specific_header_image($image_to_remove) {
  $uploaded_header_images = get_uploaded_header_images();
  $header_image_id = null;

  foreach ($uploaded_header_images as $image) {
    if (basename($image['url']) === $image_to_remove) {
      $header_image_id = $image['attachment_id'];
      break;
    }
  }

  if ($header_image_id) {
    wp_delete_attachment($header_image_id, true);
    echo 'The specific header image has been removed.';
  } else {
    echo 'The specific header image is not found.';
  }
}

// Usage: remove_specific_header_image('header-image.jpg');