bgStretcher jQuery Plugin Allows to Add Background Image to Page and Proportionally Resize it to Fill Entire Window Area.

Framework: jQuery Listed in: Effects

Description

bgStretcher 2011 (Background Stretcher) is a jQuery plug-in which allows you to add a large image (or a set of images) to the background of your web page and will proportionally resize the image(s) to fill the entire window area. The plug-in will work as a slideshow if multiple images mode is used (the speed and duration for the slideshow is configurable).
bgStretcher 2011 has tons of new features suggested by our users. We appreciate all your feedback, and you will see below that we have implemented many new features and functions requested. Please continue to help us improve it by leaving suggestions in our comments area or you may contact us directly.

Features

Unobtrusive script, simple to setup
Works with all modern browsers
Supports single and multiple images

How to Use

1. Download bgStretcher script. The package already contains the jQuery framework.

2. Add the following code to your <head>…</head> tag to connect jQuery framework, bgStretcher plugin and CSS. (Make sure paths to files are correct.)

<script type="text/javascript" src="../jquery-1.5.2.min.js"></script>
<script type="text/javascript" src="../bgstretcher.js"></script>
<link rel="stylesheet" href="../bgstretcher.css" />

3. Use the following code to initialize the bgStretcher (see Options section below for details):

<script type="text/javascript">
$(document).ready(function(){
//  Initialize Backgound Stretcher
$('BODY').bgStretcher({
images: ['images/sample-1.jpg', 'images/sample-2.jpg', 'images/sample-3.jpg', 'images/sample-4.jpg'], imageWidth: 1024, imageHeight: 768
});
});
</script>

And if you want to initialize plugin for custom div use next:

<script type="text/javascript">
$(document).ready(function(){
//  Initialize Backgound Stretcher
$('.classname-of-div').bgStretcher({
images: ['images/sample-1.jpg', 'images/sample-2.jpg', 'images/sample-3.jpg', 'images/sample-4.jpg'], imageWidth: 1024, imageHeight: 768
});
});
</script>

4. Insert content of your page inside BODY or custom DIV:

<body>
<div class="classname-of-div">
Your content goes here...
</div>
</body>

That’s it ;) Click the Demo button to see it in action.

Options

Configuration Option	Default Value	Description
imageContainer	bgstretcher	bgStretcher will automatically build structure for the images list in a DOM tree. This parameter is ID for the images holder. Try inspecting the tree with a FireBug to get an idea how it’s constructed.
resizeProportionally	true	Indicates if background image(s) will be resized proportionally or not.
resizeAnimate	false	Indicates if background image(s) will be resized with animation. (Be careful, this may slow down some PCs if your images are large.)
images	empty	An array containing list of images to be displayed on page’s background.
imageWidth	1024	Original image’s width.
imageHeight	768	Original image’s height.
maxWidth	auto	Maximum image’s width.
maxHeight	auto	Maximum image’s height.
nextSlideDelay	3000 (3 seconds)	Numeric value in milliseconds. The parameter sets delay until next slide should start.
slideShowSpeed	normal	Numeric value in milliseconds or jQuery string value (’fast’, ‘normal’, ’slow’). The parameter sets the speed of transition between images.
slideShow	true	Allows or disallows slideshow functionality.
transitionEffect	fade	Transition effect (use also: none, simpleSlide, superSlide).
slideDirection	N	Slide Diraction: N – north, S – south, W – west, E – East (if transitionEffect = superSlide use also: NW, NE, SW, SE).
sequenceMode	normal	Sequence mode (use also: back, random)
buttonPrev	empty	Previous button CSS selector
buttonNext	empty	Next button CSS selector
pagination	empty	CSS selector for pagination
anchoring	‘left top’	Anchoring bgStrtcher area regarding window
anchoringImg	‘left top’	Anchoring images regarding window
preloadImg	false	For Preload images use true
stratElementIndex	0	Start element index
callbackfunction	null	Name of callback function

Methods

Method Name	Description
$(objID).bgStretcher.play()	Resume background slideshow
$(objID).bgStretcher.pause()	Pause background slideshow
$(objID).bgStretcher.sliderDestroy()	Destroy background slideshow

Browser Compatibility

Tested in:

MS Internet Explorer 6, 7, 8, 9
Mozilla Firefox 2, 3, 4
Opera 9+
Apple Safari
Google Chrome

Leave a Comment

Sissmic

July 11, 2011

IE 9.0 : No problem
Firefox 5.0 : KO
Chrome 12.0 : KO

Sissmic

July 11, 2011

The version of jquery seems to be an issue.
jquery 1.5.2 : OK (IE, Firefox & Chrome)
jquery 1.6.2 : Got the problem

(sorry for the multiple-posts)

Shaun

July 13, 2011

Hi there,

When I have a small browser window with a scroll bar my background image doesn’t fill it.

how can I fix this?

Sebastien

July 15, 2011

First, thanks for your nice plugin!

But…

I’m having the same issue than Jonathan Hayward. Tested with jQuery 1.5.2 as Sissmic recommended and that solved my problem.

clavier arabe

July 24, 2011

I’m having the same issue than Jonathan Hayward. Tested with jQuery 1.5.2 as Sissmic recommended and that solved my problem.

clavier arabe

July 24, 2011

When I have a small browser window with a scroll bar my background image doesn’t fill it.

l3v1tcl30s

July 25, 2011

Great plugin! Exactly what I needed. No issues implementing. Using jQuery 1.6.2

deen

July 27, 2011

There seems to be some sort of conflict b/w the last few lines in your bgstretcher.js file and when someone wishes to use li elements in their html. see this post for explanation;

http://www.sitepoint.com/forums/web-page-design-1/javascript-html-conflict-navigations-772961.html

chris

July 28, 2011

is it possibile that if i click on the slideshow it links to a different path or website.
sorry im a beginner

Darren – ajaxBlender

July 28, 2011

Jonathan, Ingvi, Sissmic, Clavier:

This is a jQuery animation issue. One way to solve it is to stop the animations if the window loses focus, and begin them again when focus returns.

jQuery(window).blur(function() { // Stop slideshow}).focus(function() { // Restart slideshow});

Other users have also fixed this by using jQuery 1.5.2

Hope this helps. Email us with your code if not, and we can try to help further.

Darren

Seppe

July 31, 2011

A tip: use the CSS3 feature background-size.
My code (I don’t need multiple images, so I didn’t include the tag):

nico

August 1, 2011

Hi,
Nice script !

In the list of “options”, I’ve founded a little error on naming things:
“stratElementIndex” instead of “startElementIndex”.
(the letter “r” is not at the good place).

So if I write directly one the keyboard instead of copying/pasting, the option is not responding).
Any possibility to have a random first element?

Michelangelo

August 4, 2011

Hello,

Please help me out? The original bgStretcher script worked perfectly for me, but when I install the bgStrecther 2 script, my page fails to load.

Thank you

mijail07

August 12, 2011

Can be used in more than one div?

grid

August 15, 2011

Hello,
I have a question. Is it possible to adjust the dimensions of the image(s) automatically with this plugin? When I remove: imageWidth: 1024, imageHeight: 768 my images will nog get their original width/height. I tried also to set resizeProportionally: true in the Jquery function. It is already a default setting: true in the Jquery lib of the plugin is what I know of. What should I do to automaticaly get the image dimensions? I want to use this plugin to load dynamic images.

Thanks in advance!
grid

ben scamels

August 18, 2011

hi – love the script however when i apply the bgstretch to the body, any item positioned with ‘bottom:’ css disappears (maybe falls behind the bgstretch image). if they;re positioned with ‘top:’ then they’re fine!

any known issues/solutions around this? might be my markup nesting…

Justin

August 19, 2011

Ben, I had the same problem yesterday. Try position:fixed; for that element and be sure it’s z-index is 2 or higher.

Tcha-Tcho

August 22, 2011

Hi buddy, I did take a look at your code and I have to say that is truly confuse-me hehehe. To stretch a image all you have to do is to calculate aspect ratio. Like this:

var img_ratio = $(’#bg’).width()/$(’#bg’).height();
var window_ratio = $(window).width()/$(window).height();
if(img_ratio>window_ratio){
$(”#bg”).css(”height”,”100%”);
$(”#bg”).css(”width”,”auto”);
}else{
$(”#bg”).css(”width”,”100%”);
$(”#bg”).css(”height”,”auto”);
}

:P don’t get me wrong, I really like the fade idea… :-)

Best regards from Brazil!

Marc

August 24, 2011

Can this script be used also for a div instead of the full window?

Michelangelo

August 24, 2011

Does anybody have any idea as to what might be my problem? Again, the original bgStretcher worked fine, but when I install bgStretcher 2, my page does not load.

Thanks very much

August 26, 2011

Great Plugin!! I have a question..how can i pause my slideshow at a particular image automatically?

Darren – ajaxBlender

August 26, 2011

Marc,

Yes, this is possible. Just use the ID or Class name of the element you want the images to load into as the jQuery selector of bgStretcher.

$(’.classNameHERE’).bgStretcher({
images: [‘sample-1.jpg', 'sample-2.jpg],
imageWidth: 1024,
imageHeight: 768
});

Hope this helps.

Darren

Darren – ajaxBlender

August 28, 2011

AK,

Thanks for your comment. You can pause the slideshow by using a callback to check the src of the image being displayed. See code below:

$(document).ready(function(){
$(’BODY’).bgStretcher({
images: ['images/image.jpg', 'images/image-2.jpg'], // image array
imageWidth: 1024,
imageHeight: 768,
callbackfunction: function() {
if ($(’.bgs-current’).find(’img’).attr(’src’) === ‘images/image-2.jpg’) {
$(’BODY’).bgStretcher.pause();
}
}
});
});

Let us know if any issues.

Thanks,

Darren

August 28, 2011

Love the plugin! One request, if I may.

When browser window gets too small, images get cropped on the right and bottom. Would be neat if they were centered and cropped on both sides, like so:

margin-left or left: (browserwidth – $(this).width())/2)
margin-top or top: (browserheight – $(this).height())/2)

August 31, 2011

here is the solution for images getting cropped.

http://resizebackground.blogspot.com/2011/08/resize-your-background-image-to-any.html

Dovy Paukstys

September 2, 2011

I love the plugin just as it is. Have a technical question though:

I’d like to be able to add to the images at any time, perhaps even randomly and let the randomized order fully work. Is this possible? Thanks.

Frederico

September 9, 2011

This is a great plugin, super simple to implement and it works on mobile Safari too! I have one question though. What should I do to show thumbnails instead of numbers in the pagination function? I’ve looked at the code and found this:
[code]
output += '';
for (i = 0; i < l; i++) {
output += ''+(i+1)+'';
}
output += '';
[/code]
Is that where the magic happens? :)

GeniusCD

September 21, 2011

Hi ajax Blender,
first of all Congrats on this plugin.. its awesome!
i really like it.

but im having trouble with it. Whenever I put this plugin into my site, the hole website slows down.
It takes to much time to load! ~ 15 sec to 30 sec.

in addition, when I apply [preloadImg true]
nothing happens, all the images are loading at the same time. I think that’s why its slowing down my website.

please advise :/, I really like this plugin.
thanks

Lacfab

September 23, 2011

The fade mode don’t work with MS Internet Explorer !!!?!!!
Mozilla OK
Safari OK.

Lacfab

September 28, 2011

I have a problem with IE8, that don’t work !
With IE7 and IE9 no problem.

With IE9 it see : “NAMEOFDIV bgStretcher-container”
With IE8 it see only : “NAMEOFDIV”

Thanks and sorry for my poor english.

LilWebbie

September 29, 2011

Hi:

Does anybody know if there is a min-height, min-width feature here? so the bg will not be squished super tiny…

Thanks!

Alberto

October 5, 2011

Hi there!

First of all thanks for this nice script!

But there is a little issue with the preloading as also pointed out by Forrest when using the 1.6 jQuery libary. With the 1.5.2 everything is fine.

Do you think that you can fix it or tell us what to change?

Thanks!

ben scamels

October 5, 2011

thanks justin!

Michael

October 13, 2011

I tried implementing this but the images will stretch beyond the browser size. It will only stretch properly if I resize the window.

Any idea what I did wrong?

Using jQuery 1.6.4, bgstretcher on a div.
Firefox 7.0.1 Mac

Darren – ajaxBlender

October 14, 2011

Michael,

Images are resized proportionally by default. This means that the plugin will get the aspect ratio of the image and its container, and stretch the image so that the shortest dimension of the image (width or height) fills the screen. If the image is rectangular, this proportional stretching will cause some of the image to be cut off.

The only way around this is to turn off the proportional stretching (possibly distorting the image), or use a perfectly square image.

Hope this helps,

Darren

Willy Harris

October 17, 2011

is it limited to 6 images? I can’t seem to get anymore?

maya

October 17, 2011

in callback function, how do you get current bg img (i.e., current bg-image? how can you tell on what bg image slideshow is currently on (this.index, something like that?)

in cycle plugin you can do this very easily in callback fn (as it’s passed params that enable this..)

how is this done in this plugin??

thank you..

maya

October 18, 2011

in callback function, how do you detect on what slide you’re on?? (can you use this.index, or something like that)???

Darren – ajaxBlender

October 18, 2011

Willy,

There is no limit to the number of images you can use with bgStretcher. However you should note that using too many images can greatly impact page load speed and performance. Be careful. :)

Darren

steveo

October 18, 2011

This script doesn’t seem to work with jQuery 1.6 (When I try to use jquery 1.6.2, the script does not work, when I fall back to the included jquery 1.5.2, it works again.)

Any ideas?

maya

October 19, 2011

where is support for this plug-in?

I won’t be able to use this plugin if can’t solve problems…

I have one bg-stretcher which is just one bg-img, on a div..
then another for the body, which has five diff images.. so initialize both bgstretchers…

$(’#wrapper_gray’).bgStretcher({
……
});
$(’body’).bgStretcher({
……..
});

BUT: if I do..

$.doTimeout(5000, function() { $(’#wrapper_gray’).bgStretcher.sliderDestroy();
$(’body’).bgStretcher.play();
});

the first line DESTROYS the bgStretcher for the body also…

( have lots of other issues, like need to flip content that goes ON TOP of bg’s along with bg-flipping.. how do I do this? again: how do you capture current bg/slide in callback function??????)

Darren – ajaxBlender

October 19, 2011

Maya,

To get the currently displayed image you can simply use:

$(’.bgs-current’).find(”img”); // “.bgs-current” is an LI element that wraps the image.

To get the zero-based index of the current image, use this:

$(’.bgs-current’).index()

Darren

Franky

October 29, 2011

For everybody who wants to use the callbackfunction option:

Don’t use quotations like:
callbackfunction: ‘mycallbackfct’

But instead do it without:
callbackfunction: mycallbackfct

Then it works…

There was no documentation, so this might help some people!

David Radovanovic

October 29, 2011

Background Stretcher on some smartphones like Droidx don’t seem to respond/work?

peter

October 31, 2011

what a nice little plugin… Anybody figure out how to do min-height & min-width?

thanks, peter

peter

October 31, 2011

I was able to hard code it by adding this to the plugin:

if (contW < 1000){contW = 1000}

Ray

November 2, 2011

When using this plugin in a site if I minimize a web browser window in Windows, when I restore it the backgrounds start fading into each other very quickly, as if it paused while it was minimized and is now trying to catch up. It will eventually go back to normal speed. I’m using Chrome. Anyone else have this problem or know how to resolve it?

Meander365

November 6, 2011

Adding the script just before the closing body tag generates a “More than one bgStretcher” error. Adding the script to the header fixes this, but as per best practices, I want to include it as the end of the document.

Any ideas?

Rob

November 8, 2011

NIce work guys! Great plugin, just what I was looking for.
Not being that familiar with Javascript, I was wondering if there is any kind of browser check that I could include on the page load to check for older browsers which do not support the plugin, and if applicable, redirect to a compatible static version of the page for those browsers.

Simone

November 9, 2011

I don’t want to repat other comment users , but you realy did a great job. realy.
I’m writing beacouse i have a problem that i ddint fond in the comments before mine .
I need to pause the animation at the beginning , and this was easy adding $(document).bgStretcher.pause();
But then the next and prev button stop to work . Is there a way to pause the animation but beeing able to still use prev and next button ? Thx very much