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 utilises the dimensions plugin and (optionally) the mouse wheel plugin.

Examples

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

Usage

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

jQuery (I'm using 1.1.3.1 here)
the dimensions plugin
the mouse wheel plugin (if you want mouse wheel support)
jScrollPane.js (or the smaller compressed version
jScrollPane.css

Like so:

<script type="text/javascript" src="jquery-1.1.3.1.pack.js"></script>
<script type="text/javascript" src="jquery.dimensions.min.js"></script>
<script type="text/javascript" src="jquery.mousewheel.min.js"></script>
<script type="text/javascript" src="jScrollPane.min.js"></script>
<link rel="stylesheet" type="text/css" media="all" href="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)

Downloads

You can download this plugin in a number of ways. Easiest is the zip file which contains all the files used in these example pages. Alternatively you can download the indivdual files from the links above. jScrollPane is also available in the jQuery svn repository.

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 plugin page on the jQuery site.

Support

All support requests should be made through the jQuery mailing list.