Here is a full screen slideshow in Javascript, without using flash, and I wanted to tell you how I did it, and how you can do it too. I will talk a bit about Javascript here, but you will be able to download the jQuery plugin I have without needing to know much, if all you want is to implement the gallery.

First of all, I wanted to use the jQuery library. It is a small compact little library that makes operations like selecting parts of an HTML document easy. It is cross platform too, so the likely hood if it working on Safari, IE, and Firefox is high.

Next, I went looking for a jQuery plugin that did the image scaling already. I ended up with a plugin called bgStretcher from The main idea behind this plugin, is that it takes an image, places it in its own div that appears to be the background, then stretches the image to fill the browser window. This plugin was close to what I wanted, but it was missing a few things. First, I wanted to be able to navigate through the images with buttons, not just a slideshow. That was a simple matter of adding some onClick handlers and calling new methods in the javascript. jQuery has the ability to ask for the .next() or .previous() html item, so once I had the current image selected, it was easy to find the next or previous.

Then I wanted to be able to handle albums, not just one list of images. That was harder. Instead of just supplying a list of images to bgStretcher, you now pass albums to bgStretcher2. You identify the album before you pass the list of images.

  albums:{'Landscapes':['images/landscape1.jpg', 'images/landscape2.jpg', 'images/landscape3.jpg'],
          'People':['images/people1.jpg', 'images/people2.jpg', 'images/people3.jpg'],
          'Flowers':['images/flowers1.jpg', 'images/flowers2.jpg', 'images/flowers3.jpg'],
          'Night':['images/night1.jpg', 'images/night2.jpg', 'images/night3.jpg']},
  album: 'Landscapes', imageWidth: 1200, imageHeight: 800

This way you pass a name of the album that I use to assign all images in that album with that class. I then can use a jQuery selector to select all images with that class. Now I can navigate from image to image within the album. Note: One thing that is brittle about this, is that your menu items need to match these album names.

var current = $(containerStr + ' LI.'+$.fn.bgStretcher.settings.album).filter('.bgs-current');

This ends up more like this:

var current = $('#bgsretcher LI.Landscapes').filter('.bgs-current');

That line will select within the bgstretcher div all the LI elements with a class of Landscapes. It then narrows in on the currently selected one with the filter. I could have done it all with one string, but thought the addition of the filter made it clearer.

Now, if you are looking at the HTML and not finding a bgstretcher div, or the LI elements that contain images, don’t worry, it’s because they are not there. At least not in the static page. They get generated in the _genHtml() function at start.

The last thing to do was to modify the next and previous functions so that they would stick to selecting items within the current album. That turned out to be similar to the selector above for curent, but I just needed to get the ‘:first’ element that had the album class attached.

Once the Javascript was working I wanted to spruce it up a little bit. I used a menu plugin called lavalamp from Ganesh. In its default config, the plugin has a orange image around the menu. I kind of liked it, but it wasn’t quite the right size for the items I had, so I had to disable it. I think you could generate another image the right size and make it work, but I didn’t get to trying that.

The lavalamp plugin also uses another plugin, called easing. It provides the bouncing effect you see when moving the mouse around the menu. I think this is a great example of how well plugins work with jQuery. The base language extension is small and compact, but you can easily add functionality with plugins, and they can even interact together.

If you would like to use this code to create your own full screen slideshow image gallery, I have provided a download of the files required. I won’t get much into the details of installation because it is so simple. There is one index.html file, a css folder with the styling, and a js folder with the Javascript files. On my site I have a images folder that I placed all my images into, but for the download, I simply referenced some of my images from flickr to make the download smaller. Now, remember, if you are putting this up, you might want to host the images locally, because it is actually against the terms of service of flickr to not link back from the image to flickr. I don’t have that linking ability in my script right now.

The only thing that you need to do is prepare some images and change the list of albums and images in the index.html file. Also, remember that the album names, and the menu titles need to be the same, so don’t forget to modify the menu too. That is just how the script works. You can add or subtract albums by adding or subracting more LI elements. Just follow the pattern in the index.html file.

The last line in the images setup Javascript is the album to start on, and the images height and width. The images will size best if they are about the same size and about the height and width that you state in the file here.

Update (2011/04/03):

The code has been bumped to 2.2. I have added a property fitImageToBrowser and defaulted it to true. Seems most people would like their images to be full screen but not clip any of the image. Well, that’s just not possible. If you want to fit the long edge of the image to the long edge of the browser window and set the other to have the letter box effect, then this property is the one for you. If you liked the old functionality, just set it to false.

Also, if you want to get rid of the lavalamp menu, then remove the script tag for it in the html. Then in the bgstretcher2.js file, comment the _configureLavaLamp() line. You can now style your menu however you would like.

[drain file 17 show tableRow]

Download Name Version Size Updated Hits

81 thoughts on “bgStretcher2

  1. Pingback: Full Screen Slideshow in Javascript |

  2. Amazing script – thanks!

    I was wondering where I would start if I wanted to incorporate titles or notes with the photos, without embedding them in the images? Any ideas?


    • You would need to have a div, like the menu at the top where you could place the info. You would need to provide the info I suppose in another parameter to be passed in to the javascript initialization. Then that value could be placed in the new div when the image is changed.

  3. What size do the images need to be? px x px? I am finding alot of bg stretchers that are inconsistent between safari and FF. This one has a small difference, but not as bad. It might just be you sized the images better then other sites.

    • No particular size. I would suggest they all be the same. There is an option to indicate the initial size but only one for all images. You can see if you view source that I used 1200×800 px images. Lots of people tell me they don’t see my signature so I might go wider still next time. The only difference I see with safari firefox and chrome is due to the different viewport size in the browsers due to tool bar and status bars and the like.

  4. I would like to have the same gallery, but instead of adjusting the size of the pictures as being 100% of the width of the browser’s page, I would like it to adjust to the height of the browser’spage. In this way, the whole picture is always show. I would proble get empty sidebars if I have a portrait picture format, but i believe this is better then missing a part of the picture. The whole composition of the picture is important to me. How do I do that? (knowing that I am a newbie to jquery)?

    • What the script does right now is to re-size the image by making the width of the image fit the width of the browser window. Instead of doing that, you would have to find the “best inside fit”. You would need to see if the image is portrait or landscape, then both the height and width of the window, then see which way of resizing would fit the entire image in the window. I had looked at doing this, but haven’t got around to it yet.

    • Julio if you want the whole image to always be displayed, sized to page hight and are willing to have sidebars you should probably consider placing and sizing the image with css only. Just use jquery scripts for image replacement control, if wanted. I have used this method successfully in the past.

      min-height: 100%;


  5. I would like the script to re-size the image by making the height of the image fit the height of the browser window. As simple as that. How do I change the script to do this?

    • Up to you. If you want to have it resize on the height instead, you will run into the same issue as now, but with landscape images that are wider than the window. Look at the _resize() method in the bgStretcher2.js file. You won’t need anything specific to jQuery to deal with it.

  6. I succeeded in making the change i wanted. I changed the line 63 to

    imgW = winH / ratio;

    But I want to do two more things that I dont really know how:
    1- I would like to NOT have de fade in / fade out effect.
    2 – I would like to start the page in the PAUSED mode, instead of the slideshow starting straigth away when you opne the page.

    How do I do that?

    Thanks for the help.

  7. One more question: Can I take this away from the page I am doing based on yours? What is this for?

    var gaJsHost = ((“https:” == document.location.protocol) ? “https://ssl.” : “http://www.”);
    document.write(unescape(“%3Cscript src='” + gaJsHost + “’ type=’text/javascript’%3E%3C/script%3E”));

    try {
    var pageTracker = _gat._getTracker(“UA-12086205-1”);
    } catch(err) {}

    • That is the code for my google analytics account. Wouldn’t do you any good. It shouldn’t be in the code you can download. I should put up a new version, but you can just remove both of the script pieces at the bottom.

  8. Pingback: Aperture 3 vs Lightroom 3 Beta 2 |

  9. Hi there

    Nice script – how would I slow down the animation…or rather the time on each image?


    • The time between images is set by the property nextSlideDelay. It was set to 3000, and I just changed it to 5000. I was thinking it was a little fast. It seems that every 1000 is about a second. It is used when calling the setTimeout standard javascript function.

  10. Hi Chris,
    first I would like to thank you for all the help, and the great script, I have been using in my own page .

    But I relalised that there is a little bug in my page, then I checked on your pade, and you also have the same bug. When the slideshow is paused, whenever you click on a new album, the first time you click on next or prev, it does not work. you have to click a second time to get it going. This hapens everytime you change the album. How can we fix that?


    • I do see what you mean. The current image class is not being applied correctly, until the first click. That sets it on the first image. I need to see if there is a good way to fix it.

    • Hi Chris,

      I was wondering if you had some time to look at this issue.

      I am afraid that if people are not stubborn enough, they might not click twice on the next button to see the work. It would be pretty bad.


  11. AWESOME SCRIPT!! One question… would I have to go into the .js file to update the speed? Right now, its a little bit too fast? Please advise. Thanks once again for providing the downloadable script for us to use… Greatly appreciated!!

    • I mentioned earlier, that the property is called nextSlideDelay. In the bgStretcher2.js file, at the bottom, the default is set to 3000. On my own site I think I have 5000 now. You can override this default by passing in the property from the html page. There is a bit of javascript where the bgStretcher object is setup. Here we pass in the albums, and the default image width and height. You can set any defaults here.

  12. Hi there,

    First thanks a lot for your plugin, works great for me!

    Now, I would like to call the _resize function in the bgstretcher2.js when a specific event happens within a javascript in my main html file.

    Just _resize(); didn’t work…
    Thanks for your support.


    • Matt, you can call some of the functions like this: $(document); but others like _resize() aren’t meant to be called that way. They aren’t public, they are part of the constructor. You would have to make a public version of the method.

  13. Hi Chris …
    this is a great script …

    i really am a newbie to all this …
    so here is my question…
    can i implement this script in a Rapid Weaver Theme?

    • I don’t see why not but I don’t have rapid weaver or know what their themes look like. Your on your own with that one ๐Ÿ™‚

  14. Chris hi, great script! Is there a way of adjusting the code so the fonts are not transparent?



  15. The bgStretcher2 code has been updated. The issue of the slideshow “getting lost” when clicking rapidly on albums has been fixed. See new readme.txt.

  16. Pingback: New Version of bgStretcher2 |

  17. Hi,

    Is it possible to change the image from a link? I have this setup to add bgimg to a div and it works, but cant get it to change image from thumbnail. Like this…

    $(‘.thumb’).click(function() {
    var imgu = $(this).attr(‘rel’);
    $(“#content”).bgStretcher({images: [imgu]});

    • Anything is possible ๐Ÿ™‚ Are you trying to change one image? The menu at the top works to change albums. You could replace the text links with images if you wish. If you call the .bgStretcher() function again it would try to redraw the

    • and tags that make it work. Not positive what you are trying to do.
      • Well this works as slideshow on pages when loaded with the images already in the array. But there’s a page where only one image is loaded at a time. The one loaded on page load, and what I’m trying to do that wont work is change the one image by calling that function again… $(โ€œ#contentโ€).bgStretcher({images: [imgu]}); but what happens is the image that was there then just fades in and out… and the new image does not load. So clicking does something, but not what is expected. How do I call the function to make it work and replace the onloaded image with the linked image? Thanks for your help.

        • The current script is not intended to work that way. There is no simple way to do that. The script as it works now, creates some html based on the array you give it. It is intended to be run only once per page. If I were you, I would take the code that does the math to stretch the image and start from there. If you only have one image at a time, there is no need for all the other code.

  18. Chris, I just came across your modified version here and love it! It’s very classy. I do have two questions however.

    First: Is there a way where I could click on a link (say a thumbnail) and have it load a particular image in the background? Ideally, I’d like to display thumbnails of shirts (from my clothing line) and then onclick have a larger version display in the background (with the option to resume the slideshow).

    Second: I have a 300px wide column on the left of my page. Is there a way I can have bgstretcher2 load in the rest of the page but not under that column? Like say I have a table… I want it to load in a particular cell which takes up all of the page but that 300px column to the left of it. Right now the column goes over it, but that hides part of the image.

    Any suggestions/help would be greatly appreciated!

    • Both are things that have been asked for, but they are not possible right now. The first, clicking on a thumbnail might work if they were all loaded via the normal script, but would have to have a different method to select the correct image for display. It wasn’t really designed as a “lightbox”. Second, the script works by looking at the max size of the screen, but might work to look at the max size of a div, you could try using that div name in the resize method and see if it works.

  19. hi chris, is it possible to to add in normal hyperlinks to the top navigation? ex. “landscapes I people I flowers I about me I contact”?

  20. I have been meaning to update the boring old front door of my site for sometime and maybe this will do the trick. I very much like the idea of full screen images that stay in proportion.

    Do you think there would be a way to have each of the images load one per day or once per browser REFRESH? Instead of being an automatic slideshow?

    Although I made my site myself (such as it is) it has been a long time since I dabbled in any html or javascript and I am absolutely new to jQuery.
    PS: apart from the code I like the photography on your site as well.

  21. can you tell me how to remove the automatic slideshow? i would like to only use the previous and next buttons!

    thanks ryan!

  22. Hi,
    this slide is amazing!
    I have a question,
    i would like to add a link that thakes the style of the command’s buttons (the color orange that follow the mouse), but it’s not working.
    How can i add?
    or ho can i make a menu with this effect so it’s the same of the slide’s commands?

  23. I’m having some trouble getting this to work with a site I’m building. I’m trying to use it with just 1 “album” because the only functionality I need vs. the stock script is the ability to manually cycle through images. when I try to fake it with 1 album and no lavalamp it won’t show any images at all (whereas the stock script was working fine when the array “images” was defined. any tips on getting this up and running?

    • The original script that I started with didn’t have lava lamp, a menu or albums. Maybe that is all you need. Otherwise I would check the album definition. There are lots of places that an errant bracket or comma causes it to die.

  24. Hi Chris, Is it possible to add an image to trigger the play/pause text? I managed to change the prev/next text with simple symbols, but I can’t manage to get a play/pause button working?

    • I haven’t tried it, but I don’t see why the image wouldn’t work. Just replace the text for prev/next with your images. I am not sure if lava lamp doesn’t work with images. You could try not using that.

      • Hi its a little late but i saw this great page and i was working on it a little, if anyone has the same problem with the play/pause text and want to use one image u can simply add it like a background image and then add the text-ident: -9999px so the texts hides and u have tha bg image working =)

  25. Hi Chris,

    I’ll try to express myself differently,
    i’ve placed a slideshow on following link,
    (lower left corner)
    now I managed to replace the prev and next buttons with symple images,
    but i would also like to have a simple play/pause button, instead of the standard text,
    but i can’t get it to work,


  26. Hi Chris,

    Very useful script you share.

    I am wondering if it is possible to disable the autoplay function? And have a normal next previous features..

    • Of course. Just remove the slideshow functionality from the menu (pause/start). Then find the location where the imageHeight is defined on the main page. Add another parameter slideShow: false. That should do it.

  27. Hi Chris
    This is an amazing script. The only thing that is missing is the facility to keep the setting when a new page is loaded. So if the user doesn’t want it to keep changing the image and pauses one this is setting is carried forward. I guess it could be done with a cookie ? Any ideas ?
    Apart from that BRILLIANT

  28. i would like to change “var initW = settings.imageWidth” into the actual imagewidth of the image, not a predefined setting. is this possible?

    • The value there is the starting point for the light box effect. It does that so that the box shows up right away, before the image is scaled. The issue right now is that the script uses that h/w to find the ratio to scale the images. You would need to change quite a bit to fix it to only scale the one image. I just cropped all my images to the same size to avoid the issue.

  29. I am about to install your fabulous script and I was wondering… is there an easy way to add/assign a sound file to each album? I want it to play just like an Iphoto slideshow with music ๐Ÿ˜‰

  30. Hi

    What a great script! thanks.

    One problem I am having…is there away to centre the image vertically in the background rather than the current top left? When the browser window is very wide, but with a small height (my client likes to view the site at full screen on his 16:9 laptop with lots of tool bars) only the top half of the image shows and the bottom half is cropped off. It would be better the crop was from both top and bottom and the vertical centre of the image remained in the centre of the window. Is there a way to do this?

    thanks again for the great work.

    • You need to pick your poison. The script currently scales to fit width, which can leave the bottom chopped off if there isn’t space. If you don’t like that, you have options. 1) scale both directions which will distort the image and the script supports this 2) change code to scale the image to the height and chop off the sides 3) scale to only fit screen which will give black bars on sides because the image is too small 3) modify your images so they have a 16:9 aspect ratio so they will fit better on your clients screen

      • Chris,

        Thanks for the quick reply. If anything, only option 3 (modify images to 16:9 aspect ratio) would be an acceptable option, but I really would prefer to find a way to adjust the display position so that that the images are vertically centred rather than locking to the top of the browser window. Are you saying that this is not possible to do? If these were displaying as css background images a simple position: left center; would do the trick…

        thanks again for your help.

  31. Hi Chris,

    first thanks a lot for the time you took to develop bgStretcher2.
    I’m looking for an another way to highlight the current menu album name. I’ve tried this:

    $('.album').click(function() {

    with a specific CSS attributes to the class .current_menu_item, but I have no idea why it doesn’t work (I’ve already done some website menu like this). Any suggest?

    Thanks in advance.

      • How can I remove it properly?
        It seems that the slideshow doesn’t work without lavalamp.


      • Allright, the problem came from lavalamp! I can’t remove it entirely but I reduced it as this:

        Now it works! Thanks ++

      • You need to remove the lavalamp javascript include in the html. Then you need to comment one line in bgStretcher2.js script. Look for the _configureLavaLamp method and comment that out. It causes an error that halts the script and doesn’t execute my script any further. I should find an easier way to remove that.

  32. Hi Chris!
    First of all thanks for this slideshow, it’s brilliant!
    I was wondering how could I randomize the order of the pics so anytime I enter the web there’s a different image as background?
    Thanks a lot!

    • Currently, the script is using jquery to get all the images in an album, and loop over them. It would be a bit of a change to do it completely random. I don’t have the time to write that change right now.

  33. I’m having a problem where the slideshow doesn’t start right away. (I have to click around the menu and wait a bit before it starts). Your sample site loads immediately though. Any ideas?

  34. Is there a way to get the semi-transparent menu bar at top to be full page width while keeping the menu text centered?


  35. I’m having a really weird issue. I initially started out my project with the original bgstretcher, then my client decided that only the default gallery should be fullscreen, and rest should fit browser, so I switched to this one. I’ve made my own gallery selection system already though…

    Anyway, I’m having a really weird problem. The images aren’t resized proportionally. They are actually stretched vertically to be bigger than they actually are. Any tips?

Comments are closed.