Big Image Handling in WordPress

Last updated on November 9, 2023

Big images have a special treatment in WordPress to save bandwidth.

Problem

You upload an image whose width or height is greater than 2560 pixels and WordPress automatically resizes the image to a smaller size.

Explanation

Each time an image is uploaded to the Media Library, WordPress compares if the image width or the image height exceeds a threshold. The default threshold is 2560 pixels and it can be customized using the 'big_image_size_threshold' filter.

If the width or the height exceeds the threshold, the image is scaled down. The threshold is used as the maximum width and height. The operation conserves the aspect ratio of the image.

The resized image is then used as the full-width version, but WordPress keeps the original image in the uploads folder. It can be retrieved using the function wp_get_original_image_url() .

Disable the scaling

WordPress does not execute the scaling procedure if the 'big_image_size_threshold' filter returns false. Add the following code to disable this feature.

add_filter('big_image_size_threshold', '__return_false');

Adjust the threshold

Add this code to set the threshold to a custom value.

/*
 * Sets the threshold used in the scaling of big images.
 */
function ns_set_big_image_size_threshold(){
    $custom_threshold = 5000; // 5000 pixels, adjust as desired
    return $custom_threshold;
}
add_filter('big_image_size_threshold', 'ns_set_big_image_size_threshold', 10, 0);

Special case

WordPress does not apply the scaling procedure in the case of PNG images.

Source code

The source code developed in this tutorial is available here.

Managing Attachments in WordPress

Introduction

Basic Operations

Advanced Topics

Resources