Posted by & filed under WordPress.

Many words have been written explaining the differences between “Responsive” and “Adaptive” designs. I think of Responsive design as mainly related to device size and resolution and how the website layout will adjust depending on the device. Adaptive design has more to do with the device hardware — speed, power and special capabilities that a desktop computer may not have — like a touch screen for instance.

In my mind, the two go hand-in-hand. Consider image handling. Sure, you’ve got your responsive layout all set up and you’re using the classic method to resize your images on the fly using CSS:

#main img {
max-width: 100%;

Works great on desktops with a high speed internet connection, but what about on a mobile using 3G? Do you really want to send a 200K, 600 x 300 image file and have CSS shrink it down to fit the screen? Of course not. It would be much better to send smaller image file to those devices. That’s where Adaptive Images comes in.

The hard work has already been done thanks to Matt Wilcox and is free to download from his site, The files and (really good) detailed instructions are all there. Apparently there was a WordPress plugin created that used his code, but it is no longer maintained and does not seem to work anymore. But that’s okay! It’s really easy to implement on your WordPress site. Here’s how I did it:

First, download the adaptive-images.php file and place it somewhere on your site. I placed it into the /library/ subfolder inside my theme. Now open it up because you will need to make at least one adjustment. You have to tell it where to save the new, cached image files that the adaptive-images.php creates. I also adjusted the resolution break-points. A snippet from my finished file is below with the lines I altered highlighted:

/* CONFIG ----------------------------------------------------------------------------------------------------------- */

$resolutions   = array(768, 640, 480, 320); // the resolution break-points to use (screen widths, in pixels)
$cache_path    = "wp-content/uploads/ai-cache"; // where to store the generated re-sized images. Specify from your document root!
$jpg_quality   = 75; // the quality of any generated JPGs on a scale of 0 to 100
$sharpen       = TRUE; // Shrinking images can blur details, perform a sharpen on re-scaled images?
$watch_cache   = TRUE; // check that the adapted image isn't stale (ensures updated source images are re-cached)
$browser_cache = 60*60*24*7; // How long the BROWSER cache should last (seconds, minutes, hours, days. 7days by default)

/* END CONFIG ----------------------------------------------------------------------------------------------------------

Easy! Upload the altered file and make sure to create and upload your new image cache folder as well. As you can see in the snippet above, I placed mine in my /uploads/ folder.

The next step is only slightly more difficult, but only because you’ll need to work inside your .htaccess file. Open that and add the following code:

<IfModule mod_rewrite.c>
# Adaptive-Images -----------------------------------------------------------------------------------

# Add any directories you wish to omit from the Adaptive-Images process on a new line, as follows:
# RewriteCond %{REQUEST_URI} !some-directory
# RewriteCond %{REQUEST_URI} !another-directory

RewriteCond %{REQUEST_URI} uploads

# Send any GIF, JPG, or PNG request that IS NOT stored inside one of the above directories
# to adaptive-images.php so we can select appropriately sized versions
RewriteRule \.(?:jpe?g|gif|png)$ windcompanionwebdesign/wp-content/themes/wcwd-2013/library/adaptive-images.php

# END Adaptive-Images -------------------------------------------------------------------------------

Again, I only had to adjust two lines. Line 27 tells the server which folder to watch. The /uploads/ folder, of course! And line 31 tells the server where the adaptive-images.php file resides. Again, this can be anywhere on your site but I think it makes sense to keep files you’re using for a specific theme inside that theme.

Step three is simple. Just place the following line into your header.php file, somewhere in the <head> before any other javascript is loaded:

<script>document.cookie='resolution='+Math.max(screen.width,screen.height)+'; path=/';</script>

That’s it, you’re done! Sit back and enjoy the peace of mind that comes from knowing that people visiting your site from mobile devices are being sent nice, mobile-sized images! Doesn’t that feel better?

Again, much thanks to Matt Wilcox. Make sure to check out his site:

16 Comment on “Using Adaptive Images in a WordPress Responsive Design”

  1. Will

    Great tutorial! I was looking for a way to implement this for a site im working on but it doesn’t seem to work for me. That could be that i’m using the nextgen gallery though with the wp-supersized plugin for a fullscreen background slideshow. Not sure why though.

    I have even put the php file in my root to test. Also set it to watch all folders except the specific theme folder (using !themefolder) but still i dont see any images being created in my ai-cache folder. not sure whats up with that.

    Any ideas? Does it parse all subfolders automatically?

    • Andy Johnsen

      I would try deactivating those two plugins, then load your site on a mobile device and then check your ai-cache folder. If you still don’t see images there it’s probably a matter of how your paths are set up in the adaptive-images.php file and/or your .htaccess file.

  2. Matt

    I’m a bit puzzled, I’ve tried a few times over and over again and i can’t get this to work. I’ve put together a basic theme with Twitters Bootstrap included (css/jquery stuff) all working nicely. I’ve got fluid images in place, and am at present checking this with a featured image, and an image inserted into a post (both are set to use the Full Size image) currently the fluid images are working perfectly, scaling to fit containers as they should. Oh and I’m using a responsive layout with breakpoints.

    So I opted to add the above to the site/theme – what I’m not certain of is the fact it never seems to ever generate an image (the ai-cache in my site root says empty) I’m using the default locations for uploads (so wp-content/uploads/2013/03 with date changing as it would with wordpress) my .htaccess file is as follows (included is the default wordpress stuff as well)

    # BEGIN WordPress

    RewriteEngine On
    RewriteBase /
    RewriteRule ^index\.php$ – [L]
    RewriteCond %{REQUEST_FILENAME} !-f
    RewriteCond %{REQUEST_FILENAME} !-d
    RewriteRule . /index.php [L]

    # Adaptive Images Start
    RewriteCond %{REQUEST_URI} http://bootstrap.sgc/wp-content
    RewriteRule \.(?:jpe?g|gif|png)$ http://bootstrap.sgc/wp-content/themes/onepage-bootstrap/framework/adaptive-images.php
    # Adaptive Images END

    # END WordPress

    I’ve even opened up the ai-cache folder’s permissions so anyone can do anything to it (worth a try…).

    Now when i fiddle with the two lines in .htaccess i get one of two situations. Firstly it ignores whatever is there (or so it seems) and just serves up the big image – seemingly adaptive-images isn’t being executed. Secondly i just get a broken image – which suggests a-i is working, but something else is up… presumably a path?

    Many thanks in advance if you can shed any light on this (I’m also using latest WP 3.5.1, and have no plugins installed, I am doing all this on my Mac, using MAMP Pro to work as server – nothings wrong with that I’m sure as i’ve got loads of sites all running nicely).


    • Andy Johnsen

      I would try removing the “http://” from your paths in the .htaccess file and see if that helps. Then I would check the path to your ai-cache file in adaptive-images.php. If none of that works I would suspect that using this method on your local server might be the issue.
      Good luck!

      • Matt

        Thanks for the reply, i played and played with the htaccess file changing paths etc with no success at all. So i copied it up the the internet (just in case) and started playing around there.

        I started by placing everything in the root (adaptive-images.php, ai-cache folder) and managed to get it all working. Basically you have to add in the htaccess code, before the WP rewrites start as follows:

        #BEGIN WordPress

        RewriteEngine On

        #Adaptive-Images ———————————————————————————–
        #Add any directories you wish to omit from the Adaptive-Images process on a new line, as follows:
        #RewriteCond %{REQUEST_URI} !ignore-this-directory
        RewriteCond %{REQUEST_URI} !wp-content/themes
        RewriteCond %{REQUEST_URI} !wp-content/plugins
        RewriteCond %{REQUEST_URI} !wp-content/plugins
        RewriteCond %{REQUEST_URI} !wp-includes
        RewriteCond %{REQUEST_URI} !wp-admin
        #Send any GIF, JPG, or PNG request that IS NOT stored inside one of the above directories
        #to adaptive-images.php so we can select appropriately sized versions
        RewriteRule \.(?:jpe?g|gif|png)$ wp-content/themes/onepage-bootstrap/framework/adaptive-images.php
        #END Adaptive-Images ——————————————————————————-

        RewriteBase /
        RewriteRule ^index.php$ – [L]
        RewriteCond %{REQUEST_FILENAME} !-f
        RewriteCond %{REQUEST_FILENAME} !-d
        RewriteRule . /index.php [L]

        Now we’ll have to check in case WP updates mess with this code, but thats another day.

        I then updated the path to the adaptive-images.php file to the one located in my theme. All working.

        The thing thats confusing about all this is that most likely the whole thing was working when i posted before – its just that in testing it we have to keep in mind that the JS that provides the info for the image to be selected takes the screen measurement – not the browser window (being a mac user i’m rarely working in full screen unlike windows peoples) so no matter what i was doing ti was always showing me the largest version of the image (because my screen size was being detected, not window size).

        So make sure you test this on an iPhone, iPad or something else (or mess with desktop resolution) and thats when i started seeing the cached files being created – ftp to your site, and make sure you hit refresh when checking, as I think half of my issues could have been solved earlier and quicker.

        As an extra i did alter the JS you copy to the head of your site (header.php in WP) to make use of window.innerWidth and window.innerHeight (in place of screen.width and screen.height) – you have to refresh the page each time, but with this you can see the smaller images loading as they should – but innerWidth and innerHeight are not supported below IE8 (not end of the world but you know…).

        Hope this helps, or give s a bit more insight to others.

        • Andy Johnsen

          Glad to here you got it working and thanks for the detailed description of the steps you took. I’m sure it will help other readers!

          And just to re-iterate, you should always check on a mobile device as the default settings will not cache images if you simply resize your browser window.

  3. Sam

    Something you might want to add in here — is where to add in that code into the htaccess file. I think mine is not working because of that.

    Mine currently looks like

    # BEGIN WordPress

    RewriteEngine On
    RewriteBase /
    RewriteRule ^index\.php$ – [L]
    RewriteCond %{REQUEST_FILENAME} !-f
    RewriteCond %{REQUEST_FILENAME} !-d
    # END WordPress

    (I apologize if this is obvious… still new).. where do I put in the #Adaptive Images code?

    • Andy Johnsen

      Hi Sam,
      I use W3 Total Cache which adds a lot of code to my .htaccess file. So I added the code snippet near the top of the file, before any of the #BEGIN WordPress stuff.

      Take a look at Matt’s response above, too. He addresses where he put his code snippet.

      Hope that helps!

  4. Mary

    This is definitely working better than when I tried to follow the directions on So thanks for getting me to the point where uploading the htaccess doesn’t break my screen.

    But it seems in some cases my images aren’t being resized properly. Most notably on my page here: .

    On my computer screen it is perfect. Scales right across the whole width of the page like I want it to. But when I look at it on my cell phone, it is much wider than the page.

    Any thoughts?

    I followed your directions almost exactly. Except my adaptive-images.php is in my root. And I used this:
    $resolutions = array(1382, 992, 480, 320); // the resolution break-points to use (screen widths, in pixels)


    $jpg_quality = 90; // the quality of any generated JPGs on a scale of 0 to 100

    • Andy Johnsen

      Hi Mary,

      Glad you found it helpful. I took a quick look at your page on my desktop and on my mobile. I think the image display issues are theme related, not adaptive-images related. For instance, the large image at the top should have a “width:100%” declaration in the css so it will scale in size. Also, there are div elements below that with inline css declarations that will force those elements to be wider than a mobile display.

  5. Greg

    Dumb question but what size/res of the image should I upload first. Okay put a high res jpeg and then have adaptiveimages.php set all the sizes? Or should I have a highly compressed image at twice the pixel width?
    Can I include two subdirectories for images since I’m using a CMS?

    • Andy Johnsen

      Hi Greg,
      You can adjust the image compression with Adaptive Images by using the $jpg_quality setting. If you already compressed the images and are content with that, I would set $jpg_quality = 100.

      And yes, you can have Adaptive Images watch multiple folders. Just add more rewrite conditions. For example:
      RewriteCond %{REQUEST_URI} uploads_folder_1
      RewriteCond %{REQUEST_URI} uploads_folder_2

  6. Robin

    Thanks for the tutorial.
    Just want to know if this will work if I insert my images by links from another source and not directly uploaded into WordPress?

    My problem is that images are not resizing itself when viewed on mobile, but only those images that are inserted as links.

    • Andy Johnsen

      Hi Robin,
      I have not tried with images linked from other websites. If it does work, and your setup is correct, you should see the resized images start populating your “wp-content/uploads/ai-cache” folder.

  7. Mikedefieslife

    How should we setup our CSS to work with this? do we need to set CSS break points in device-width or is just max-width ok? Then do we need to set img{ max-width: 420px;} for the 420px break point we have in the php file?

    I’m running this on my website. Example page

    I’m finding that images don’t seem to be loading from cache when visiting on my mobile(s). The cache creates them (sometimes it seems), but it looks to me like the original images are still loading.

    My .htaccess and adaptive-images.php files are all correct.

    • Andy Johnsen

      Hi Mike,

      Setting an image max-size with CSS will not affect the actual file size of that image, just the display size. The Adaptive Images program does not care what about CSS size settings. It looks at the screen size being used and compares that with the $resolution settings to find any images cached at that size. If there are any, it will serve that image instead. If not, it will create one.

      If your .htaccess and adaptive-images.php files are correct, perhaps you have a caching plugin that is overriding adaptive-images.php?

      Let me know if you find a solution. It may help other readers with similar issues.


  1.  wordpress:How can I serve different images depending on screen size with wordpress – Wordpress Questions
  2.  Bilder für das Web optimieren, Ladezeiten verkürzen