jScrollPane - cross browser styleable scrollbars with jQuery and CSS

jScrollPane is a cross-browser jQuery plugin by Kelvin Luck which converts a browser's default scrollbars (on elements with a relevant overflow property) into an HTML structure which can be easily skinned with CSS.

jScrollPane is designed to be flexible but very easy to use. After you have downloaded and included the relevant files in the head of your document all you need to to is call one javascript function to initialise the scrollpane. You can style the resultant scrollbars easily with CSS or choose from the existing themes. There are a number of different examples showcasing different features of jScrollPane and a number of ways for you to get support.

How to use

It is very simple to use jScrollPane. You will need to download the necessary files and place them on your server. Then you just need to include the relevant files in the <head> of your document:

<!-- styles needed by jScrollPane -->
<link type="text/css" href="style/jquery.jscrollpane.css" rel="stylesheet" media="all" />

<!-- latest jQuery direct from google's CDN -->
<script type="text/javascript" src="http://ajax.googleapis.com/ajax/libs/jquery/1.4.2/jquery.min.js">
</script>

<!-- the mousewheel plugin - optional to provide mousewheel support -->
<script type="text/javascript" src="script/jquery.mousewheel.js"></script>

<!-- the jScrollPane script -->
<script type="text/javascript" src="script/jquery.jscrollpane.min.js"></script>

Then you just need to initialise jScrollPane on document.ready (using a selector which will find the content you want to apply jScrollPane to):

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

There are plenty of different ways to use jScrollPane - either passing in different settings when you initialise it or by using the API. Each of these different use cases is covered by an example linked to from below.

Download

You can always find the latest code for jScrollPane on its github page. You can either check out this entire website (including all examples) via git, or you can use the handy github functionality to download a zip of the repository.

The particular files that you need are:

jquery.jscrollpane.css - the basic CSS styles that are needed for jScrollPane to work.
The jQuery library - although I recommend including this directly from a CDN like I do above and in all of the examples.
jquery.mousewheel.js - The jQuery mouseweel plugin. This is optional but recommended, include it to allow people to scroll your content using their mouse wheel.
mwheelIntent.js - The mwheelIntent plugin. This is totally optional but can increase the usability of the mousewheel in nested scroll areas. See demo.
jquery.jscrollpane.min.js - the actual javascript file for jScrollPane (you can also get the unminified version if yu want to see the sourcecode and read the comments).

Simple examples/ tests

These examples show very basic functionality and exist so that I can test that any changes to jScrollPane work cross browser and don't cause any new problems. Note that these examples aren't meant to look pretty, they merely highlight different bits of functionaity which are available. If you want examples of jScrollPane looking good then check out the themes.

Demo showing basic scrolling (horizontal, vertical and combined)
Demo showing basic scrolling (horizontal, vertical and combined) with arrow buttons
Demo showing how the contents of the scrollpane is focused as you tab to it
Demo showing how you can set "caps" and "gutters" to change the size and positioning of the scrollbar relative to the content it is scrolling
Demo showing how you can restrict the minimum and maxium size of the drag part of the scrollbar
Demo showing how the arrowScrollOnHover option makes the arrow buttons automatically scroll the content when you hover over them
Demo showing how the verticalArrowPositions and horizontalArrowPositions options can change the position of the arrow buttons
Demo showing how you can use the scrollTo and scrollBy methods of the API
Demo showing how you can use the scrollTo and scrollBy methods of the API along with the animateScroll which enables animation when scrolling
Demo showing how you can make internal links automatically scroll the scrollpane (and how external links can link directly into content within a jScrollPane)
Demo showing that jScrollPane can work correctly on elements which are initially set to be invisible via CSS
Demo showing vertical scrolling with multiple panes on the same page and adding dynamic content and then reinitialising one of the panes
Demo showing how you can manually reinitialise the scrollpane if you add dynamic content to it
Demo showing how you can change the content of your jScrollPane via an ajax call and can reinitialise the scrollpane once the new content has loaded
Demo showing how jScrollPane can be set to automatically reinitialise itself on a timer via the autoReinitialise parameter
Demo showing how autoReinitialise can also be used so that content with images in it displays correctly in jScrollPane
Demo showing how jScrollPane can be reinitialised when the width of it's container changes and will update to fill the available space
Demo showing how jScrollPane can be reinitialised when the height of it's container changes and will update to fill the available space
Demo showing how jScrollPane can be applied to an entire page so that the browser's default scrollbars for the page are replaced. This demo also shows that you can nest jScrollPanes and everything will still work correctly.
Demo showing how jScrollPane can be used to style the scrollbars in an iframe.
Demo showing how vertical scrollbars can also appear on the left hand side of content
Demo showing that no scrollbars are created when the content is too short to scroll
Demo showing the events that are dispatched by an element you apply jScrollPane to.

Themes

You can style jScrollPane however you like using simple CSS. To give you some ideas, here are a variety of different themes which you are free to download and use or modify:

Lozenge - lozenge shaped sliders and small arrow buttons

Support

Before trying to get support please check if your problem is a known issue or if it is mentioned in the FAQs. If your issue is a new one and you can't find any information about it then you can try one of the following two options:

Using the StackOverflow site. This is probably the place you are most likely to get a quick answer as many Javascript experts spend time on the site. It also provides niceties like pretty formatting of posted sourcecode.

If you ask a question on the site make sure you add the tags "jquery" and "jscrollpane" as I will be monitoring these tags to try to provide support.
Through the jScrollPane google group - sign up and then you can start a discussion (either by email or through the web interface).

Please remember to use the search field at the top of the group's homepage to search the archive to find out if your question has been answered before.

If you have contacted support and established that your problem is definitely a bug then you can raise an issue on the project's github site.

History

jScrollPane was originally developed in December 2006. Since then it has been constantly updated to fix bugs and add new features. The change history since November 2008 is available in the jScrollPane git repository. In August 2010 a major rewrite was undertaken, starting from a blank canvas and adding long awaited features like horizontal scrolling and automatic reinitialisation. If you want to find old versions of jScrollPane then you can check out the changelog.

Credits

Thanks to Hoppermagic for creating the jScrollPane logo! And thanks to Mark Reed, Philip Leff and Erwin Odendaal for sponsoring the development of v2 of this plugin (particularly to enable horizontal scrolling).

Donate

jScrollPane is a personal project that is open source for anybody to use as they want to. If you (and your clients!) like jScrollPane then please consider donating to it's ongoing development. You can do so via Pledgie or Paypal using the images below: