Managing images in WordPress is a core part of theme and plugin development. Whether you are building a custom slider, an image optimization tool, or simply auditing your site's performance, you often need to know exactly what image sizes are available. WordPress doesn't just store one version of your upload; it generates a suite of thumbnails based on both core settings and custom definitions in your theme.

In this guide, you will learn how to programmatically retrieve every registered image size, including their widths, heights, and crop settings. We will cover the modern approach for WordPress 5.3 and above, as well as legacy methods for older environments.

Why You Need to List Registered Image Sizes

By default, WordPress creates several sizes for every image you upload: Thumbnail, Medium, Medium Large, and Large. However, most modern themes and plugins register additional custom sizes using the add_image_size() function.

As a developer, you might need this list to: 1. Build a UI: Create a dropdown for users to select a specific image size in a custom block or widget. 2. Debug Layouts: Verify that your child theme is correctly overriding or adding sizes. 3. Optimize Performance: Identify unnecessary image sizes that are bloating your server storage.

The Modern Approach: Using wp_get_registered_image_subsizes()

If you are working on a site running WordPress 5.3 or higher, there is a dedicated function that makes this process incredibly simple: wp_get_registered_image_subsizes(). This is the most efficient and "correct" way to get a comprehensive list of all image dimensions.

This function returns an associative array where the keys are the image size names (e.g., 'thumbnail', 'post-thumbnail') and the values are arrays containing the width, height, and crop status.

$all_sizes = wp_get_registered_image_subsizes();

print_r($all_sizes);

This approach is superior because it combines both the default WordPress sizes (which are stored in the options table) and the additional sizes (which are stored in a global variable) into a single, clean output.

Retrieving Sizes in Older WordPress Versions

Before WordPress 5.3, developers had to manually merge different data sources to get a full picture of image dimensions. The default sizes (thumbnail, medium, large) are stored in the wp_options table, while custom sizes added via add_image_size() are stored in the global variable $_wp_additional_image_sizes.

Here is a robust helper function that works across older versions to gather all image data into one array:

/**
 * Get all the registered image sizes along with their dimensions
 *
 * @global array $_wp_additional_image_sizes
 * @return array $image_sizes The image sizes
 */
function _get_all_image_sizes() {
    global $_wp_additional_image_sizes;

    $image_sizes = array();
    $default_image_sizes = get_intermediate_image_sizes();

    foreach ( $default_image_sizes as $size ) {
        $image_sizes[ $size ][ 'width' ] = intval( get_option( "{$size}_size_w" ) );
        $image_sizes[ $size ][ 'height' ] = intval( get_option( "{$size}_size_h" ) );
        $image_sizes[ $size ][ 'crop' ] = get_option( "{$size}_crop" ) ? get_option( "{$size}_crop" ) : false;
    }

    if ( isset( $_wp_additional_image_sizes ) && count( $_wp_additional_image_sizes ) ) {
        $image_sizes = array_merge( $image_sizes, $_wp_additional_image_sizes );
    }

    return $image_sizes;
}

When you call this function, it returns a structured array like this:

Array
(
    [thumbnail] => Array
        (
            [width] => 150
            [height] => 150
            [crop] => 1
        )
    [medium] => Array
        (
            [width] => 300
            [height] => 300
            [crop] => 0
        )
)

Hook Timing: When to Call the Function

One common mistake developers make is trying to fetch image sizes too early in the WordPress execution cycle. If you call these functions in the root of your functions.php file, you might only see the default WordPress sizes because your theme or other plugins haven't registered their custom sizes yet.

Always wrap your logic in a hook that runs after the theme is initialized, such as init or after_setup_theme.

add_action('init', 'log_my_image_sizes');

function log_my_image_sizes(){
    $sizes = wp_get_registered_image_subsizes();
    error_log( print_r( $sizes, true ) );
}

Practical Application: Displaying Sizes in the Admin Dashboard

Sometimes you want to see these sizes without digging into the code. You can create a simple dashboard widget that lists all registered sizes for quick reference. This is especially helpful when working with complex child themes.

/**
 * Register a dashboard widget to display all image sizes
 */
function register_imagesizes_dashboard_widget() {
    wp_add_dashboard_widget(
        'imagesizes_dashboard_widget',
        'Registered Image Sizes',
        'display_imagesizes_dashboard_widget'
    );
}
add_action( 'wp_dashboard_setup', 'register_imagesizes_dashboard_widget' );

function display_imagesizes_dashboard_widget() {
    $sizes = wp_get_registered_image_subsizes();
    echo '<ul>';
    foreach($sizes as $name => $values){
        echo '<li>';
        echo '<strong>' . esc_html($name) . ':</strong> ';
        echo esc_html($values['width']) . 'px &times; ' . esc_html($values['height']) . 'px';
        if($values['crop']) {
            echo ' (Cropped)';
        }
        echo '</li>';
    }
    echo '</ul>';
}

Best Practices and Common Pitfalls

Hard Crop vs. Soft Crop

When reviewing your list of sizes, pay attention to the crop value. A true value (hard crop) means WordPress will cut the image to match the exact dimensions. A false value (soft crop) means WordPress will resize the image proportionally until it fits within the specified width and height without cutting anything off.

The 'medium_large' Size

Since WordPress 4.4, a medium_large size (768px wide by default) is automatically generated to better support responsive images (srcset). You won't see this in the Media Settings page in the admin dashboard, but it will appear when you use the functions discussed in this article.

Memory Usage

While fetching the list of sizes is lightweight, remember that every size you register results in another file being created on your server for every upload. Use the methods in this guide to audit your sizes and remove any that your theme isn't actually using.

Frequently Asked Questions

What is the difference between get_intermediate_image_sizes() and wp_get_registered_image_subsizes()?

get_intermediate_image_sizes() only returns an indexed array of the names of the sizes (e.g., ['thumbnail', 'medium']). In contrast, wp_get_registered_image_subsizes() returns a detailed associative array including the width, height, and crop settings for each size.

Why are some sizes missing from the list?

If a size is missing, it is likely because the code calling it is running too early. Ensure your code is hooked into init. Additionally, if a plugin registers a size only on specific admin pages, it may not appear in your list unless you are on those pages.

Can I use these functions to change the image sizes?

No, these functions are for retrieval only. To change image sizes, you should use the update_option() function for default sizes or add_image_size() to redefine custom sizes with the same name.

Wrapping Up

Understanding the image sizes available in your WordPress environment is essential for building high-performance, responsive themes. For most modern projects, wp_get_registered_image_subsizes() is the only function you need. By using the dashboard widget or helper functions provided above, you can gain full visibility into your site's image processing and ensure your media library stays organized and efficient.