QueryLoader2 – Preload your images with ease

Gaya Design is back in business and hitting hard with a redo of the 2009 script QueryLoader. I kept getting e-mails and comments about it and thought I had left it just hanging there for way too long. It had become very outdated. So here it is: version 2 of QueryLoader!

QueryLoader2 - Preload your images with ease

Download Download on Github Example See it in action!

A direct link to the zipfile:

View the example here:

What QueryLoader2 does is simply scanning the given elements for images (and background images) and preload them before the website is visible.
This version has been modified to make it easier for users to implement (especially those who are already into jQuery.)

QueryLoader2 currently works with jQuery v1.9.1 and in IE version > 7, Chrome, Safari and Firefox.

How to use QueryLoader2:

Include the script in the head section of your webpage.

<script src="path/to/file/jquery.queryloader2.js" type="text/javascript"></script>

Be sure to add it after you include jQuery.

Now call QueryLoader in a $(document).ready() like this:

$(document).ready(function () {

To make it work for iOS devices, use this code:

window.addEventListener('DOMContentLoaded', function() {

That's it! You're done.


queryLoader2( object options );

You can add options to loader.

string backgroundColor Background color of the loader (in hex).
string barColor Background color of the bar (in hex).
int barHeight Height of the bar in pixels. Default: 1
bool deepSearch Set to true to find ALL images with the selected elements. If you don't want queryLoader to look in the children, set to false. Default: true.
int barHeight Height of the bar in pixels. Default: 1
bool percentage Set to true to enable percentage visualising. Default is false.
string completeAnimation Set the animation type at the end. Options: "grow" or "fade". Default is "fade".
function onLoadComplete This function is called once the loading is complete. This is handy when changing the animation at the end.
function onComplete This function is called once the loading and animation are completed.


As you might have noticed I put my code on GitHub. This makes it easier for me to manage my code and give you updates if you or me find any bugs.
You can also file issues with the script here and fork it to make changes / fix bugs. If you send me pull requests I will take a look as to what you have changed and commit it if it is an addition.

Liked this article? Sharing is caring!

1,000 Comments on this subject

    • Adi said:

      hy all, i have found out a problem, for example if the browser has to many requests to the webhost , clearing the cache ctrl + F5 , sometimes the preloader get stuck almost at the end of fully loading, i think is something about the loading time,

      • Arujei said:

        I can confirm this issue as well. Doing a hard reload (shift + F5 or ctrl + F5) will cause some images not to load up with preloader. Reloading normally will fix it.

      • Samir said:

        Is this sorted as I am still facing this issue. I have a page quite big with data crossing 1.7MB. Can you please let me know.

  1. Daniel said:

    Looks great! Thnaks a lot for the effort.
    Is there a way to have it “open up” when finished like the previous version did? Means not to fade out, but to have the halfs of the screen slide up // down…

  2. Damon said:

    Hi, this looks pretty cool, im wondering though, is it possible to select what gets preloaded?

    for instance, on my website i will have my portfolio page, id like al the button images in my website aswell as the thumbnails for the lightbox, but i dont want the full sized images to be preloaded or itll just take too long.

    Is that at all possible?

    • Mr. X said:

      Hey Daniel!!!
      Ich bin auch aus Deutschland!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!


      Coll oder!!! Das Ladedingens!!!!!!!!

  3. Joe said:

    Thanks for this – another great preloader!
    I had the last version on my site and it worked ok. I am struggling to get this one to work however… was wondering if I could be cheeky and get you to have a quick look!? jrharris.co.uk

    thanks again!

  4. Gaya said:

    @Damon: yes, you can preload what you want to using a selector. For example, if you want to preload only the images in your #portfolio container which have the class .thumb you can do this: $(“#portfolio .thumb”).queryLoader2();
    Good luck!

    @Daniel: great addition to the script indeed :) try to get involved through Github if you have other issues or additions you’d like to see.

    @Joe: Try to clean up the part of your html page. You need to include jQuery just once. And try to include and call QueryLoader at the bottom of the . I also tested QueryLoader for the latest version of jQuery and am not sure if it works with version 1.4.3

  5. Vic said:

    @Gaya: Thanks for new loader.

    I added the following to my stylesheet to make the loader work with my site:

    #qLoverlay {
    z-index: 50;

    @Joe: I think you could change the font by adding a selector to your stylesheet, like:

    #qLpercentage {
    font-style: (desired font)

  6. Roberto.c said:

    A little bit addition:
    barHeight -> define the height of the loading bar

    add default value in qLoptions var:

    var qLoptions = {

    barHeight: “1px”,

    edit qLbar var (around line 102)

    height: “1px”,
    height: qLoptions.barHeight,

    That’s all :)

    Very good preloader!!!!!!!!!!!

  7. Roberto.c said:

    I have found a lack around line 32, in onLoadComplete function definition:

    onLoadComplete: function () {
    if (qLoptions.completeAnimation == “grow”) {
    $(qLbar).stop().css(“width”, “100%”).animate({
    top: “0%”,
    height: “100%”
    }, 500, function () {
    $(qLoverlay).fadeOut(500, function () {

  8. Dan said:

    @Gaya awesome script, definitely what I needed and easy to plugin. I got it to work on my end, but since I’m experimenting with my site, I’m also running to a specific problem. It seems like the script isn’t supporting multiple css backgrounds in CSS3 (http://www.w3schools.com/css3/css3_backgrounds.asp). I’m sure it has to do with the function that finds the url string of images.

    I’ve found ways to go around it by using extra divs/z-index to apply different backgrounds, but would like CSS3 multiple backgrounds to work. Any insight on changing the script to support it?

    Thanks for your contribution and time.

  9. Fxck said:

    More of that CSS3 stuff. It tries to load css gradients and obviously fails..

    “NetworkError: 400 Bad Request – http://recyplast.cms.local/-moz-linear-gradient(50%%200%
    “NetworkError: 404 Not Found – http://recyplast.cms.local/191
    “NetworkError: 404 Not Found – http://recyplast.cms.local/77
    “NetworkError: 404 Not Found – http://recyplast.cms.local/47
    “NetworkError: 404 Not Found – http://recyplast.cms.local/166

  10. Gaya said:

    @Fxck: will look into the CSS3 stuff and Modernizr. Never occured to me that those might be used.
    Can you give a more detailed description on the 0%? Which browser are you using and which page does it stay at 0%? Maybe I can dig up some reasons there.
    You can also file these issues on GitHub, it will be easier for me to manage it there.
    Thanks for the feedback

  11. Fxck said:

    On this page http://recyplast.f13.cz/ (you have to refresh a couple of times, sometimes it works, sometimes it doesn’t) and in chrome 15.0.874.106, on the other hand, it happens only on my site, not in your demo, so it’s most likely colliding with the other plugins, or my rather messy code itself.

  12. dani said:


    Thank you so much for this fantastic/fantastic looking preloader.

    The loader keeps getting stuck at 71%…not sure why.

    I’m using it on a site that has animations that are triggered by the document ready function.

    Any help would be greatly appreciated

    • paul said:

      Make sure all css files that reference an image, has the image in the correct location. I too ran into this problem, where it loaded to 70% … I spent a few hours debugging, and realized I had added prettyphoto, yet forgot to add the images referenced in the css in the correct folder … easy to do, and easy to forget … but once you have this corrected, it loads perfectly!

  13. dani said:

    Ok…last message.

    In safari, the preloader works correctly after the first load and animations are displayed accurately.

    However, if I press shift+refresh and empty the cache the preloader works, but upon opening the animations have already happened

    Still no luck with firefox.

  14. Kaumac said:

    same here, the loader gets stuck on pages with more content, and only when theres already some cache, opens fine on first time. It does get stuck on Chrome and Firefox, works in IE, haven´t tested it on other browsers yet. I´ve posted to GitHub also.

  15. Les said:

    I just can’t seem to get this (or the old version) to work. I follow your instructions correctly… use the same version jquery as you. Is it possible that it’s a server thing? I’m using wordpress too jsut FYI…. could tat be a problem? I’m pretty noobish when it comes to most things so if you could have a peek that would be great.


    It just doesn’t work for me and loads the page normally.

  16. Gaya said:

    Thanks for the feedback all.

    @dani: you can try to put the animation stuff in the onComplete event of queryLoader so it fires once QL is done.

    @Kaumac: Thanks for posting on GitHub. I will look into it and respond there.

    @Les: Try to call the script at the bottom of the it might be interferring with other scripts.

    @The9fan: Can you give me an example of your page? I haven’t test it with swf mediaplayers

  17. Fxck said:

    So, the problem in my case is this line

    if ($(element).css(“background-image”) != “none”) {

    from time to time ‘$(element).css(“background-image”)’ always returns ‘none’, so the problem is most likely not with my code. Could be because there’s too many nodes or something.

  18. piero said:

    Hey, great plugin, fairplay.

    One thing, percentage doesnt work for me…!

    $(“body”).queryLoader2({backgroundColor:’#ffffff’,barColor:’#4D6D24′, percentage: true,barHeight:’30′});

    placed just before the …

  19. dani said:


    Thank you so so much. It is now working perfectly in Safari.

    Still no luck with firefox. It still stalls at 71%. Not sure why since the animations are now linked to the onComplete of queryLoader.

  20. Matthew said:

    Nice to see v. 2! I’m experiencing the loader getting stuck at around 70% as well in Safari and Chrome as well. I’ve run the script in the head and footer but neither helps. In v1 there was a problem with CSS3 background gradients… perhaps this is still a problem with this version?

  21. Will said:

    First, great job. Can’t wait to utilize this (currently updating my site with this). Also, I’ve discovered an issue with the qLbar in the loader. I hooked up jquery 1.7, you know, trying to keep up and all. But my loading bar was acting jumpy, kept resetting, wouldn’t expand across the page. I found that somehow, it was rendering the width in px instead of percentage, which is what was causing that. Switched back to jquery 1.6 and it works fine. Just a bug I came across, FYI.

  22. Renaud said:

    Hi gaya : )

    I use you’re pretty loader for my website and it help me to wait until my full page load. I use to read a xml with ajax and put my html code using cdata, images and video as well. But theses one sadly do not been include in the loader. I mean it’s work fine but not for this xml content I append in the page.

    My problem is that i’m using a javascript floating menu but this one do not work until the whole page is loaded.. And i’m unfortunately a beginner with jquery !

    I will appreciate if you have a idea to include it ! I think this will finalise my website if you find a solution ^^

    Here is the beginning of the code I use :
    $.ajax( {
    type: “GET”,
    url: “lib/data.xml”,
    dataType: “xml”,
    success: function(xml)

    Big thanks,

  23. Sam said:

    Looks awesome Gaya, however like many others here I’m having an issue with the preloader being stuck at a certain percentage ( depending on the browser ).

    For example, on Chrome,Firefox and Safari it gets stuck at 71%
    in IE at 99%

    Any help would be greatly appreciated as I really love this pre-loader :)

  24. Jeff said:

    I’m new to jquery and web development in general. I’ve loaded the plugin and there are couple of things I’m not getting right.

    1) the overlay only fills the top portion of the screen instead of filling the whole screen.

    2) I’m not sure how to get the options to work. When I use this code for example: window.addEventListener(‘DOMContentLoaded’, function() {

    I would expect to get a red overlay. But is stays the default black. Am I inputting this incorrectly?

    3) is there any way to use a div for the overlyay? I’d like to have the overlay contain a logo and some text.


  25. Renaud said:

    Hey Jeff, you should use it that way for example :

    $(document).ready(function () {
    backgroundColor : ‘#262626′,
    barHeight : 10,
    percentage : true,
    deepSearch : true,
    onComplete: function() {
    $(bghide).fadeOut(“slow”); // your stuff


    And you can customise it by changing the code inside the .js here : line 95

    var createOverlayLoader = function () {
    qLoverlay = $(“<your html stuff

    and the css is bellow in the code


  26. Jeff said:

    First part works great, Now I’m trying to get fancy by putting a splash image in the middle of the whole thing. I can’t seem to insert an image in the .js. Text and tags seem to work fine but when I insert this:

    <qLoverlay = $("

    I get errors. Any idea how to insert an image over the overlay color?
    thanks again,

Leave your reply

Your email address will not be published. Avatars through Gravatar.


You may use these HTML tags and attributes: <a href="" title=""> <abbr title=""> <acronym title=""> <b> <blockquote cite=""> <cite> <code> <del datetime=""> <em> <i> <q cite=""> <strike> <strong>