Scrolling Parallax Plugin for jQuery - Documentation

Created by Jon Raasch

The Scrolling Parallax Plugin for jQuery is used to create a parallax animation effect that is bound to the browser scrollbars and user mouse wheel. When scrolling down a web page with the parallax applied, the background scrolls at a different rate from the page, creating a sense of depth.

Download Scrolling Parallax Plugin for jQuery

Basic use of Scrolling Parallax

The Scrolling Parallax Plugin can be used to automatically apply an image as a fully-stretched background. Simply pass the path to an image:

$.scrollingParallax('img/parallax-background.jpg');
    

The plugin can additionally be used on any jQuery object:

$('div.parallax').scrollingParallax();
    

When using Scrolling Parallax on a jQuery object, be sure to set its position CSS property to fixed. Forgetting this won't cause any errors, but it might cause the plugin to incorrectly place the object on page load.

You can also pass arguments to both of these functions, just pass the arguments as an object:

$.scrollingParallax('img/parallax-background.jpg',{
    bgHeight: '200%',
    reverseDirection : true
});
    

Or pass arguments to a parallax applied to a jQuery object:

$('div.parallax').scrollingParallax({
    staticSpeed: 2,
    loopIt : true
});
    

Remember the shorthand syntax for jQuery objects — comma separated key : value pairs. Make sure not to leave a trailing comma or it will throw errors in IE.


Examples showing Scrolling Parallax in action


Layout options for Scrolling Parallax

bgWidth (CSS String)
CSS value for the parallax image width. Only works with the image path method.

bgHeight (CSS String)
CSS value for the parallax image height. Only works with the image path method.

bgRepeat (Boolean)
Set to true to cause the background image to tile using it's native dimensions rather than stretching to fill the dimensions of the parallax. Only works with the image path method.

appendInFront (Boolean)
Set to true to append the background image rather than the default prepending. Only works with the image path method.


Animation options for Scrolling Parallax

staticSpeed (Number)
Set to a number to use a static speed for the scrolling animation. Pass a ratio of the document scroll speed, for instance passing .2 makes the parallax scroll at .2 times the rate of the document scrolling. Passing 2 instead would scroll the parallax at twice the speed of the document. Set this to false or 0 to have the plugin automatically determine a speed that maximizes scroll area.

staticScrollLimit (Boolean)
Set to false if you want the parallax to not limit the scroll distance when using a staticSpeed. The default true stops and anchors the parallax when it reaches its end.

loopIt (Boolean)
Set to true when using a staticSpeed to cause the parallax to loop if it reaches it's end. This will work regardless of the setting of staticScrollLimit.

reverseDirection (Boolean)
Set to true to cause the parallax scrolling to move in the opposite direction.

enableVertical (Boolean)
Set to false to disable the parallax animation for vertical scrolling. By default this is set to true, but should be turned off if unused for better performance.

enableHorizontal (Boolean)
Set to true to enable the parallax animation for horizontal scrolling. By default this is set to false for performance reasons.


Horizontal scrolling options

staticSpeedX (Number)
When using horizontal scrolling set this to a number to use a static speed for the horizontal scrolling animation. Similar to staticSpeed above.

staticScrollLimitX (Boolean)
When using horizontal scrolling and a static horizontal speed set this to false to disable the limit on the horizontal scroll distance. Similar to staticScrollLimit above.

loopItX (Boolean)
When using horizontal scrolling and a static horizontal speed set this to true to cause the horizontal scrolling animation to loop when exceeds its bounds. Similar to loopIt above.

reverseDirectionX (Boolean)
When using horizontal scrolling set this to true to cause the horizontal scrolling animation to move in the opposite direction. Similar to reverseDirection above.


Other options for Scrolling Parallax

disableIE6 (Boolean)
Set to true to disable Scrolling Parallax in IE6 altogether

disableIE6Anim (Boolean)
Set to false to enable animation in IE6 (by default this is set to true because of performance issues with IE6)


Known issues, bugs, etc.

IE6 not supported
Scrolling Parallax supported IE6 before a number of features were added, and IE6 support is forthcoming. However the IE6 solution will probably be pretty choppy. Currently IE6 has issues with appending the backgrounds and the parallax animation.

Choppy animation on older computers
Scrolling quickly on an old computer can cause choppiness in the parallax animation. This will likely remain unresolved.

Animation jumps when using mouse wheel in some browsers
This is unavoidable in browsers that treat the mouse wheel scroll as a single large jump rather than a series of small jumps. The plugin uses animation to mitigate this jumping, however it has to be done quickly so the scrolling animation doesn't lag behind the page.

Animation jumps when looping
Instead of a smooth loop with tiled images, the loop jumps from the end back to the top. A fix for this is forthcoming.


Licensing of Scrolling Parallax

Scrolling Parallax is released under the FreeBSD license:

Copyright (c) 2009 Jon Raasch (http://jonraasch.com/)

Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:

  1. Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.
  2. Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.

THIS SOFTWARE IS PROVIDED BY JON RAASCH 'AS IS' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL JON RAASCH OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

The views and conclusions contained in the software and documentation are those of the authors and should not be interpreted as representing official policies, either expressed or implied, of Jon Raasch, who is the man.



Make A Donation