Skip to content


Subversion checkout URL

You can clone with
Download ZIP
Tree: af46250397
Fetching contributors…

Cannot retrieve contributors at this time

117 lines (73 sloc) 3.69 KB


Backstretch is a simple jQuery plugin that allows you to add a dynamically-resized, slideshow-capable background image to any page or element. The image will stretch to fit the page/element, and will automatically resize as the window/element size changes.


There are a couple of examples included with this package, or feel free to check it out live on the project page itself.


Include the jQuery library and Backstretch plugin files in your webpage (preferably at the bottom of the page, before the closing BODY tag):

<script src="//"></script>
<script src="jquery.backstretch.min.js"></script>
  // To attach Backstrech as the body's backgroun

  // You may also attach Backstretch to a block-level element

  // Or, to start a slideshow, just pass in an array of images
  ], {duration: 4000});



The ratio of the width/height of the image doesn't always jive with the width/height of the window. This parameter controls whether or not we center the image on the X axis to account for the discrepancy. (type=Boolean, default=true)


This parameter controls whether or not we center the image on the Y axis to account for the aforementioned discrepancy. (type=Boolean, default=true)


This is the speed at which the image will fade in. Integers in milliseconds are accepted, as well as standard jQuery speed strings (slow, normal, fast). (type=Integer or String, default=0)


The amount of time in between slides, when using Backstretch as a slideshow, expressed as the number of milliseconds. (type=Integer, default=5000)

Slideshow API

Once you've instantiated Backstretch, you can access its instance via that element's data attribute. There are many actions that you can perform on an instance, though most of them are only applicable if you've created a slideshow:

// Start a slideshow

// Pause the slideshow

// Advance to the next slide


Jump to the slide at a given index.


Display the previous image in a slideshow.


Advance to the next image in a slideshow.


Pause the slideshow.


Resume a paused slideshow.


Destroy the Backstretch instance. Optionally, you can pass in a Boolean parameter, preserveBackground, to determine whether or not you'd like to keep the current image stretched as the background image.


Backstretch will fire a "" event everytime a new image loads. If you listen for that event, you can, for example, coordinate other changes to coincide with your slideshow.


Version 2.0

  • Now accepts an array of images to create a slideshow
  • Can attach Backstretch to any block-level element, not just the body
  • Deprecated "speed" option in favor of "fade" for fadeIn timing
  • Added "duration" option, and Slideshow API

Version 1.2

  • You can now called backstretch twice, and it will replace the existing image.

Version 1.1

  • Added 'centeredX' and 'centeredY' options.
  • Removed 'hideUntilReady' option. It looks pretty bad if you don't hide the image until it's fully loaded.
  • Fixed IE img onload bug.
  • Now supports iPhone/iPad orientation changes.
Jump to Line
Something went wrong with that request. Please try again.