Note: This repo is currently looking for maintainers: https://github.com/jquery-backstretch/jquery-backstretch/issues/464

Backstretch

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.

We're back in business! Merged danielgindi/jquery-backstretch, and all eyes please get back here!

Demo

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

Installation

1. Download/save the JS file from GitHub.
2. Install via Bower with the following command.

``
bower install jquery-backstretch
`

Setup

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

`html



`

Automatic resolution selection

The automatic resolution selection algorithm has multiple options to choose from.
The default behaviour is that it matches the logical width of the element against the specified image sizes. Which means that an element with a 320px width on a @2x device is still considered as 320px.
If you want 320px on a @2x device to be considered as 640px, then you can specify pixelRatio: "auto" on the specific image resolution.
However if you want to limit specific images to only be chosen if the device has a certain pixel ratio - you can specify that pixel ratio i.e pixelRatio: 2.5.

Options

| Name | Description | Type | Default |
|------|-------------|------|---------|
| alignX * | This parameter controls the horizontal alignment of the image. Can be 'center'/'left'/'right' or any number between 0.0 and 1.0. | Integer or String | 0.5 |
| alignY * | This parameter controls the vertical alignment of the image. Can be 'center'/'top'/'bottom' or any number between 0.0 and 1.0. | Integer or String | 0.5 |
| scale * | Controls the scaling mode. Can be 'cover'/'fit'/'fit-smaller'/'fill' | String | 'cover' |
| transition * | Type of transition to use. If multiple are specified, then it will be chosed randomly | String or Array | 'fade' |
| transitionDuration * | This is the duration at which the image will transition in. Integers in milliseconds are accepted, as well as standard jQuery speed strings (slow, normal, fast). | Integer or String | 0 |
| transitionEasing | The easing function that will be used for animations. | Any supported jQuery easing value | jQuery default* |
| animateFirst | If true, the first image will transition in like all the others. | Boolean | true |
| fade * | Sets transition to 'fade' and transitionDuration to whatever value was specified. | Integer or String | |
| fadeFirst | Synonym for animateFirst | Boolean | true |
| duration * | The amount of time in between slides, when using Backstretch as a slideshow, expressed as the number of milliseconds. | Integer | 5000 |
| paused | For slideshows: Disables the change between slides | Boolean | false |
| start | The index of the image in the array you want to start your slideshow with. | Integer | 0 |
| preload | How many images to preload at once? I.e. Lazy-loading can be enabled by specifying 0. | Integer | 2 |
| preloadSize | How many images to preload in parallel? If we are preloading 5 images for the next slides, we might want to still limit it to only preload 2 or 3 at once, according to the expected available bandwidth. | Integer | 1 |
| bypassCss | Avoid adding any CSS to the IMG element. I.e if you want a dynamic IMG tag that is laid out with the content. | Boolean | false |
| alwaysTestWindowResolution | Always test against window's width instead of the element's width. | Boolean | false |
| resolutionRefreshRate | Threshold for how long to wait before the image resolution will be switched? | Integer | 2500 |
| resolutionChangeRatioThreshold | Threshold for how much should the different in the resolution be before switch image | Number | 0.1 (10%) |
| centeredX | Deprecated. Still works but please do not use it. | Boolean | true |
| centeredY | Deprecated. Still works but please do not use it. | Boolean | true |

Options marked with an can be specified for individual images

Image definition

Each image in the set can be a String specifying the URL for the image, or an object with the following options, or an array of images for different resolutions to choose between.
A url can be a url to a video also.
Currently the plugin will automatically recognize a youtube url. If you pass urls to raw videos, you have to specify isVideo: true.

| Name | Description | Type | Default |
|------|-------------|------|---------|
| url | The url of the image or video | String | |
| alt | The alternative text for this image (If you want to play along with screen readers) | String | '' |
| alignX | This parameter controls the horizontal alignment of the image. Can be 'center'/'left'/'right' or any number between 0.0 and 1.0. | Integer or String | 0.5 |
| alignY | This parameter controls the vertical alignment of the image. Can be 'center'/'top'/'bottom' or any number between 0.0 and 1.0. | Integer or String | 0.5 |
| scale | Controls the scaling mode. Can be 'cover'/'fit'/'fit-smaller'/'fill' | String | 'cover' |
| transition | Type of transition to use. If multiple are specified, then it will be chosed randomly | String or Array | 'fade' |
| transitionDuration | This is the duration at which the image will transition in. Integers in milliseconds are accepted, as well as standard jQuery speed strings (slow, normal, fast). | Integer or String | 0 |
| transitionEasing | The easing function that will be used for animations. | Any supported jQuery easing value | jQuery default |
| fade | Sets transition to 'fade' and transitionDuration to whatever value was specified. | Integer or String | |
| duration | The amount of time in between slides, when using Backstretch as a slideshow, expressed as the number of milliseconds. | Integer | 5000 |
| isVideo | Tell the plugin the this is a video (if cannot be recognized automatically) | Boolean | false |
| loop | Should the video be looped? If yes, then the duration will be used to determine when to stop. | Boolean | false |
| mute | Should the video be muted? | Boolean | true |
| poster | This is for specifying the poster attribute in standard url | The url of the image | String | |
| url for