ShortPixel Adaptive Images


An easy to use plugin that can help you solve within minutes all your website’s image-related problems.

Display properly sized, smartly cropped and optimized images on your website; Images are processed on the fly and served from our CDN, in the next-gen WebP & AVIF formats, if the browser supports it.

Do I need this plugin?

If you have a WordPress website with images then the answer is: most probably yes!
Did you ever test your website with tools like PageSpeed Insights or GTmetrix and received complains about images not being properly sized or being too large? Or that you should use “next-gen” images like WebP or AVIF? Or that the website should “defer offscreen images”?
ShortPixel Adaptive Images comes to the rescue and resolves your site’s image-related problems in no time.

What are the benefits?

Imagine that you could have all your image-related website problems solved with a simple click, wouldn’t that be great?
Usually the images are the biggest resource on a website page. With just one click, ShortPixel Adaptive Images replaces all your website’s pics with properly sized, smartly-cropped, optimized images and offloads them on to the ShortPixel’s global CDN.
And for more Google love the plugin serves WebP and AVIF images to the right browsers auto-magically!

What are the features?

  • new, lightweight, pure JavaScript Adaptive Images engine (jQuery not required anymore) starting with version 3
  • same visual quality but smaller images thanks to ShortPixel algorithms
  • smart cropping – see an example
  • serve only appropriately sized images depending on the visitor’s viewport
  • lazy load support with adjustable threshold; browser native lazy loading support is also available
  • automatically serves WebP & AVIF images to browsers that support this format. Animated Gifs are supported too!
  • caching and serving from a global CDN for images, as well as CSS, JS and fonts
  • all major image galleries, sliders, page builders are supported
  • onboarding wizard which includes a tool that suggests the best settings for each site
  • Low Quality Imaage Placeholders (LQIP) support
  • support for JPEG, PNG, GIF, TIFF, BMP
  • convert to WebP and AVIF on the fly
  • adjustable size breakpoints when resizing images
  • possibility to deactivate the plugin functionality for logged-in users
  • variety of settings for an increased flexibility in the plugin functionality

Do I need an account to test this plugin?

No, just go ahead and install then activate it on your WordPress website and you’ll automatically receive 500 image optimization credits, which equals to 2.5GB of CDN traffic, or approximately 2500 visits!

How much does it cost?

When using ShortPixel Adaptive Images, only the CDN traffic is counted, if you choose to use our CDN. The free tier receives 100 image optimization credits, which equals to 500MB of CDN traffic, or approximately 500 visits. Paid plans start at $4.99 and both one-time and monthly plans are available.
Even better: if you already use ShortPixel Image Optimizer then you can use the same credits with ShortPixel Adaptive Images!

How does this work?

Different visitors have different devices (laptop, mobile phone, tablet) each with its own screen resolution. ShortPixel AI considers the device’s resolution and then serves the right sized image for each placeholder.
Let’s consider a webpage with a single 640×480 pixels image.
When viewed from a laptop the image will retain it 640x480px size but it will be optimized and served from a CDN.
When the same webpage is viewed from a mobile phone, the image will be resized (for example) to 300x225px, optimized and served from CDN.
This way, neither time nor bandwidth will be wasted by visitors.
Please note that the first time the call for a specific image is made to our servers, the original image will be served temporarily.

Other plugins by ShortPixel

WP CLI commands

Use the following WP CLI commands to clear the CSS cache and the Low Quality Image Placeholders:
wp shortpixel clear_css
wp shortpixel clear_lqips

For developers

If in Media Library there are main images which end in the usual thumbnail size suffix (eg. -100×100) please set in wp-config.php this:


If you need to do a post-processing in JavaScript after the image/tag gets updated by ShortPixel AI, you can add a callback like this:

jQuery( document ).ready(function() {
    ShortPixelAI.registerCallback('element-updated', function(elm){
        // elm is the jQuery object, elm[0] is the tag
        console.log("element updated: " + elm.prop('nodeName'));

For changing the original URL of the image, that is detected by ShortPixel, use this filter that receives the original URL:

add_filter('shortpixel/ai/originalUrl', 'my_function');

Sometimes, when the option to crop the images is active, SPAI thinks it’s not safe to crop an image, but you want to crop it anyway. Please add this attribute to force the cropping:

<img data-spai-crop="true" ....

ShortPixel Adaptive Images triggers a JS event after the initial processing of the HTML page in browser: spai-body-handled, an event after each processed DOM mutation, if at least one URL was replaced: spai-block-handled and an event after each element has its URL updated lazily (entering the viewport): spai-element-handled

In order to exclude specific images, you can also add the following attributes to the markup, inside the IMG tag:

    <img data-spai-excluded="true" ...> --> this will completely exclude from processing the image which has this attribute;
    <img data-spai-eager="true" ...> --> this will exclude the image from being lazy-loaded by the plugin;
    <img data-spai-noresize="true" ...> --> this will prevent the image from being resized by the plugin.

For adding custom replacement rules use:

add_filter('shortpixel/ai/customRules', 'my_function');

The function will receive an array and should append to that array elements with the following structure: [‘tagName’, ‘attrToBeChecked’, ‘classFilter’, ‘attributeFilter’, false(reserved), ‘attributeValueFilter’, isEager(bool)]. Starting 3.0, you can also append ShortPixel\AI\TagRule instances
A real-life example for custom image attributes, a custom srcset and a custom JSON data attribute:

add_filter('shortpixel/ai/customRules', 'spai_to_iconic');
function spai_to_iconic($regexItems) {
    $regexItems[] = array('img', 'data-iconic-woothumbs-src', false, false, false, false, true);
    $regexItems[] = array('img', 'data-large_image', false, false, false, false, true);
    $regexItems[] = new ShortPixel\AI\TagRule('img', 'srcset', false, false, false, false, false,
                    'srcset', 'replace_custom_srcset');
    $regexItems[] = new ShortPixel\AI\TagRule('div', 'data-default', 'iconic-woothumbs-all-images-wrap', false, false, false, false,
                        'srcset', 'replace_custom_json_attr');
    return $regexItems;


  • Example site metrics on PageSpeed Insights before: Low

  • Example site metrics on PageSpeed Insights after: Good

  • Example site metrics on GTMetrix before: F score

  • Example site metrics on GTMetrix after: B score

  • Main settings page

  • Advanced settings page


What happens when the quota is exceeded?

In your WP dashboard you’ll be warned when your quota is about to be exhausted and also when it was exceeded. When the quota is exhausted, the plugin will simply serve the original images from your server, without compression or resizing, until the quota resets.
The images that weren’t already optimized will be served directly from your website.

What Content Delivery Network (CDN) do you use?

ShortPixel Adaptive Images uses to offload the images – a global CDN with 54 edge locations around the world.
Both free and paid plans use the same CDN with the same number of locations.
You can independently check out how the CDN compares to other CDN providers here (wordlwide) and here (North America).

Can I use a different CDN?

Sure. Here you can see how to configure it with Cloudflare and here’s how to configure it with STACKPATH. Please note that when using a different CDN, image credits will be consumed instead of CDN traffic.
If you need further assistance please contact us

What happens if I deactivate the plugin?

You can stop using the SPAI whenever you want but this means your site will suddenly become slower.
Basically, your website will revert to the original, un-optimized images served from your server.

Are there different image optimization levels available?

Yes, you can compress images as Lossy, Glossy or Lossless.
You can find out more about each optimization level here or can run some free tests to optimize images here

I already used ShortPixel Image Optimizer, can I also use this?


What is the difference between this plugin and ShortPixel Image Optimizer?

You can see here the differences between the two services.

Where can I optimize my images? There’s nothing on my admin panel.

SPAI works differently than a regular image optimizer. Here’s what it does.

How can I make sure that the plugin is working well?

You have more information about this here.

I want to start using the plugin, what should I do?

The exact instructions for this are available here.

My images are getting redirected from, why?

Have a look at this article.

SPAI is not working well, I’m having some issues.

Please check the following things:
1) Make sure your domain is associated to your account;
2) Make sure you have enough credits available in your account;
3) Have a look at this article;
4) Take a look at our knowledge base.

If nothing seems to work, please contact us.


Works like a charm plus super quick support team. Happy to be with them!
I've been using Short Pixel AI for a few months now, and it's helped me reach a perfect A/A score on GTMetrix and 99/100 on Google PageSpeed. I use it for all of my client projects now. On the couple of occasions I've needed to reach out to their support team, they've helped me resolve issues really quickly.
SPAI is great because it makes the page experience and the scores so much better. What I like is the number of options it gives for what types of images to optimize, serve, exclude, etc. And the support is just excellent.


“ShortPixel Adaptive Images” 是开源软件。 以下人员对此插件做出了贡献。


“ShortPixel Adaptive Images”插件已被翻译至2种本地话语言。 感谢所有译者为本插件所做的贡献。

将“ShortPixel Adaptive Images”翻译成您的语言。





Release date: December 22nd, 2021
* New: if the same image is present in different sizes on the same page, it will only be loaded once and reused;
* New: added data-spai-crop in the new AI Engine, which can override the crop settings for specific images where this attribute is present;
* New: when purging the caches in WP Rocket, Swift Performance and Litespeed Cache, the CSS served by SPAI will also be purged automatically;
* Tweak: the account status in settings now takes into account the billing cycles and correctly displays the traffic information;
* Tweak: the tool-tips in the Settings look better and are more visible;
* Compat: fixed various compatibility issues with Internet Explorer in the new AI Engine;
* Fix: regex exclusions weren’t properly working in some cases, with the new AI Engine;
* Fix: a fatal error was thrown in certain configurations when WP Rocket cache was purged;
* Fix: do not replace data:image inline placeholders that are not generated by SPAI;
* Fix: the special crop on background images wasn’t properly working for retina displays;
* Fix: the new AI will load the original image if no LQIP is available;
* Fix: loading original URL for backgrounds that also have for ex. background:transparent in styles;
* Fix: elements with other inline images as backgrounds added later to the document via mutations;
* Fix: some of the settings suggested by the automatic settings tool weren’t displayed correctly;
* Fix: background images having gradient an url() with no quotes on Chrome;
* Fix: the Image Checker Tool now works properly with backgrounds handled by the new AI Engine;
* Fix: issues with background-size: auto 100%;
* Fix: if the API key was incorrect in the on-boarding wizard, you couldn’t enter it again;
* Language: 16 new strings added, 4 updated, 0 fuzzed, and 12 obsoleted.


Release date: November 24th, 2021
* Fix: Instagram galleries and feeds should be working properly now;
* Fix: the special crop parameter was multiplying the original resolution of the image on retina displays;
* Fix: AVIF was still served in some cases, even if the option was disabled;
* Fix: serve the new AI JS from the custom domain/CDN, if the JS serving from CDN is enabled;
* Fix: file type options were hidden in the settings when only AVIF was active (no WebP);
* Fix: make no resize exclusions remain lazy;
* Fix: when there were HTML comments before the DOCTYPE declaration, SPAI wasn’t working properly;
* Language: 0 new strings added, 1 updated, 0 fuzzed, and 0 obsoleted.


Release date: November 17th, 2021
* Fix: added back the jQuery dependency for the old AI engine;
* Fix: PHP warning that was showing up in certain cases;
* Language: 0 new strings added, 0 updated, 0 fuzzed, and 0 obsoleted.


Release date: November 12th, 2021
* Fix: deactivate unintentionally left active logging;
* Fix: undefined notice about video-placeholder;
* Fix: various small fixes to the new AI engine’s JS processing;
* Language: 0 new strings added, 0 updated, 0 fuzzed, and 0 obsoleted.


Release date: November 11th, 2021
* New: added Size Breakpoints option for resizing images, especially useful when the images resize a lot on various screen sizes;
* New: the necessary headers are now automatically added when using Apache, in order to avoid CORS issues with the new AI engine;
* New: added font preload support for the CDN (when a CSS file is parsed, the fonts will already be prepared for the CDN);
* New: added separate options for WebP and AVIF, for more control on these settings;
* New: added tooltips for the plugin settings for an easier understanding;
* Compat: added compatibility with the Agile Store Locator plugin;
* Compat: the placeholder image that WP Rocket uses for YouTube embeds is now automatically excluded from being processed;
* Fix: the plugin upgrade notice mechanism wasn’t working anymore;
* Fix: the parsing works now in <style> blocks when the background-image is added right after the {;
* Fix: the image dimensions are now properly retrieved from SVG files, when they have it defined either as viewBox or as width and height;
* Fix: LQIP’s were always displayed when using the new AI Engine, even if the option was disabled;
* Language: 18 new strings added, 0 updated, 0 fuzzed, and 6 obsoleted.


Release date: October 14th, 2021
* New: the new Adaptive Images engine (pure JavaScript based, no jQuery required) can now be enabled from the Behavior tab in Settings -> ShortPixel AI;
* New: option to serve the local JS files from the CDN;
* New: local fonts are now served as well from the CDN, when referred from parsed CSS files;
* Tweak: re-enabled the automatic delivery of AVIF for supporting browsers;
* Tweak: various re-wording and spelling corrections throughout the entire plugin strings;
* Tweak: the plugin is now fully tested with PHP8;
* Tweak: removed the option to revert to the 1.8.x settings upon deactivation;
* Fix: fixed various issues with different integrations (caching plugins, galleries etc.);
* Fix: when deactivating the delivery of next-generation images for certain image types, the entire option was wrongly deactivated;
* Language: 18 new strings added, 51 updated, 0 fuzzed, and 12 obsoleted.


Release date: June 30th, 2021
* Fix: issue with validating API key
* Language: 0 new strings added, 0 updated, 0 fuzzed, and 0 obsoleted.


Release date: June 29th, 2021
* Temporarily deactivate AVIF pending codec bug fix (;
* Language: 0 new strings added, 0 updated, 0 fuzzed, and 0 obsoleted.


Release date: June 28th, 2021
* New: Version the javascript in the file name in order to get around more stubborn caches;
* Fix: do not parse AJAX responses to uploads;
* Fix: nested element that has a different background – was taking the background of the parent element;
* Fix: notice in logs sometimes when domain info from server;
* Language: 0 new strings added, 0 updated, 0 fuzzed, and 0 obsoleted.


Release date: June 17th, 2021
* New: images (including the ones from CSS files) are now served automatically in the new AVIF format to supporting browsers;
* New: moved the JS detection mechanism for WebP/AVIF support directly to the CDN level, so no JS is required anymore for this;
* Language: 0 new strings added, 6 updated, 0 fuzzed, and 0 obsoleted.


Release date: June 14th, 2021
* Compat: added a constant – SPAI_ELEMENTOR_WORKAROUND – to deactivate the parsing of Elementor modules that are resulting in critical errors;
* Compat: workaround for WP Rocket that calls in certain circumstances the filter rocket_css_content with only one parameter;
* Fix: some warnings when lqip queue is not array were showing up in some cases;
* Fix: wrong array key when the no background calculation can’t determine crop size and returns just width and height;
* Fix: iPhone issues with parsing stylesheets while also improving page responsiveness while parsing them (async);
* Language: 0 new strings added, 0 updated, 0 fuzzed, and 0 obsoleted.


Release date: May 18th, 2021
* New: also parse inside <script type="text/template"> blocks;
* Fix: the background crop resize wasn’t working in several cases, which is now fixed;
* Fix: update the notification text about the next generation images served by SPIO;
* Fix: cases when a mutation has backgrounds from an existing CSS block are now properly handled;
* Fix: the special crop feature now handles correctly the situations when the width parameter isn’t the first one;
* Fix: the inline background selector will handle situations with no space before the CSS class definition;
* Fix: remove the default values for JS parameters in order to support IE11;
* Fix: the images from li elements added with data-thumb are now replaced;
* Fix: the URL exclusions are checked when replacing inside JS blocks too;
* Language: 0 new strings added, 2 updated, 0 fuzzed, and 0 obsoleted.


Release date: April 29th, 2021
* Fix: the minified version of the plugin CSS files was bigger than the not minified one;
* Fix: find local file when URL contains a path element before wp-content, that is not present on disk;
* Language: 0 new strings added, 0 updated, 0 fuzzed, and 0 obsoleted.


Release date: April 26th, 2021
* Compat: added integration with Real3D Flipbook;
* Fix: there was a “Class not found” error in some cases when purging LiteSpeed cache from our plugin;
* Fix: in some cases, the size of background images wasn’t properly set;
* Fix: protection added for very large number of product variations; the plugin will now work properly in these cases;
* Language: 0 new strings added, 0 updated, 0 fuzzed, and 0 obsoleted.


Release date: April 20th, 2021
* New: added filter shortpixel/ai/customRules for custom replacement rules;
* New: added proper lazy loading for background images;
* New: take into account the background-* CSS styles: size, position, etc.;
* New: lazy load the images in the CSS blocks;
* New: handle correctly multiple URLs in the same background-image: declaration;
* New: when running out of credits you can now have an option to top-up directly from the plugin settings;
* Compat: added an integration with the Uncode theme and its iLightBox component;
* Compat: added integration with WPC Variations Table;
* Compat: added integration with Soliloquy Slider Plugin;
* Compat: also integrate properly with Divi child themes;
* Compat: improved the integration with Elementor, all images should now be properly replaced;
* Fix: WooCommerce product variations were broken if srcset was present, but false;
* Fix: in certain cases, background images with important CSS priority weren’t properly handled;
* Fix: also remove the sizes attribute if we remove the srcset;
* Fix: replacement error when html attribute contains “..” data;
* Fix: various small fixes to settings, fonts, debug messages, ShortPixel account login and lazy loading;
* Language: 7 new strings added, 2 updated, 0 fuzzed, and 3 obsoleted.


  • please refer to the changelog.txt file inside the plugin archive.