jScrollPane

jScrollPane is a jquery plugin which allows you to replace the browsers default vertical scrollbars on any block level element with an overflow:auto style. You can easily control the apperance of the custom scrollbars using simple CSS.

jScrollPane is crossbrowser, working on all browsers that support jquery and it also degrades gracefully. If a user's browser doesn't support jQuery or has JavaScript turned off then they will see the browsers default scrollbars. If the mouse wheel plugin is included in the page then the scroll panes will respond to mouse wheel events as well.

jScrollPane is built on top of the awesome jQuery library and optionally utilises the mouse wheel plugin and the jQEm plugin

Examples

There are a number of different examples of different ways you can use jScrollPane:

• Basic scrollbars
• OS style scrollbars
• scrollTo functionality
• example of loading content into scroll pane using AJAX
• fullpage scroll and nested scrollpanes
• scrollTo functionality with different speeds
• using jScrollPane with the reinitialiseOnImageLoad parameter so that it automagically updates when any images inside it load
• an example showing tabbing amoungst form fields inside the jscrollpane
• example showing scrolling to a specific place in a jScrollPane from an external link
• using jScrollPane with jQEm so it works even when the user changes their text size in the browser
• setting the default options for all jScollPanes on a page
• [deprecated] using jScrollPane with jquery.onImagesLoad so it works even when your scroll pane contains images which haven't been loaded when you initialise it

Real world examples

Here are some examples of jScrollPane being used in the real world - they demonstrate how varied the scroll bars you can create can be.

• In the Tignes Spirit snowboard store
• In the Lisa Kline online boutique.
• On lab-au's news panel.
• On Rezo Kaishauri's portfolio site.

Usage

Just include the following files in the head of your page:

• jQuery (I'm using 1.2.6 here)
• the mouse wheel plugin (if you want mouse wheel support)
• the jQEm plugin (if you want your scroll panes to automagically resize when the user changes text size)
• jScrollPane.js
• jScrollPane.css

Like so:

<script type="text/javascript" src="scripts/jquery-1.2.6.min.js"></script>
<script type="text/javascript" src="scripts/jquery.mousewheel.min.js"></script>
<script type="text/javascript" src="scripts/jquery.em.js"></script>
<script type="text/javascript" src="scripts/jScrollPane.js"></script>
<link rel="stylesheet" type="text/css" media="all" href="styles/jScrollPane.css" />

Then you can use any query selector to select the elements you would like to apply jScrollPane and then initialise it. The following code runs when the document is ready and finds any element with a class of "scroll-pane" and then calls jScrollPane on them.

$(function()
{
	$('.scroll-pane').jScrollPane();
});

You can pass some optional parameters to the jScrollPane function. These take the form of an object with the following attributes:

• scrollbarWidth [int] - the width of the created scrollbar in pixels (defaults to 10)
• scrollbarMargin [int] - the margin to leave to the left of the scrollbar in pixels (defaults to 5)
• wheelSpeed [int] - controls how fast the mouse wheel makes the content scroll in pixels (defaults to 18)
• showArrows [boolean] - controls whether to display arrows for the user to scroll with (defaults to false)
• arrowSize [int] - the height of the arrow buttons if showArrows=true (calculated from CSS if not provided)
• animateTo [boolean] - whether to animate when calling scrollTo and scrollBy (defaults to false)
• dragMinHeight [int] - the minimum height to allow the drag bar to be (defaults to 0)
• dragMaxHeight [int] - the maximum height to allow the drag bar to be (defaults to 99999!)
• animateInterval [int] - The interval in milliseconds to update an animating scrollPane (default 100)
• animateStep [int] - The amount to divide the remaining scroll distance by when animating (default 3)
• maintainPosition [boolean] - Whether you want the contents of the scroll pane to maintain it's position when you re-initialise it - so it doesn't scroll as you add more content (default true)
• scrollbarOnLeft [boolean] - Whether the scrollbar should appear on the left hand side of the panes content (make sure your CSS also reflects this)
• reinitialiseOnImageLoad [boolean] - Whether the jScrollPane should automatically re-initialise itself when any contained images are loaded (defaults to false)

Downloads

You can download this plugin in a number of ways. Release version distributions are available from the jScrollPane googlecode site. Or the latest sourcecode is always available in the googlecode subversion repository.

Donate

jScrollPane is completely free and open source. However, if you find jScrollPane useful and you would like to make a donation towards my beer fund then please use the paypal button below to donate any amount. Thanks!

Limitations

Because the element that you turn into a scrollpane is wrapped in another element you can't apply any positional styling to it. This is a shame but the problem is easily avoided by wrapping the element in another div with the positional styling on it (like the divs on this page with a class of holder).

Bugs

Bug reports and enhancement requests should be made through the jScrollPane issues page on googlecode. All bug reports should include full details of the browser/ OS that the bug appears on and a link to a test URL displaying the bug. This is the only avenue that I can accept bug reports through as otherwise it is too hard to keep track of them.

Support

All support requests should also be made through the jScrollPane issues page on googlecode or through the comments on my jScrollPane project page.