We’re just wrapping up a site for a client and they decided that they would prefer to have custom scroll bars, rather than the OS scroll bars that browsers will render by default. James did a little research and point me to the jQuery jScrollPane plugin. I took a quick look at the documentation – it looked good and seemed easy enough to implement. Once I got it into place on the site, I started to notice some problems. These problems aren’t so much related to the jScrollPane plugin, as they are to how the browser loads content.

I noticed that if I loaded a page, the scroll bars would display exactly as I would expect — however, if I did a shift+refresh, only part of the content would appear in the scrollable area. Other times, I’d notice that divs just wouldn’t appear at all.

Based on these issues and a fair amount of troubleshooting, I gathered up some important caveats for using the jScrollPane plugin.

1. Always set a height on the div that you’re applying the scroll pane to.

   The jScrollPane plugin does a calculation to determine the height of the wrapping div that controls the scrolling. The best way that I found to ensure that the scroll bars will scroll the right amount of the content.

2. Ensure that divs are not hidden when applying the jScrollPane

   Based on my googling, this appeared to be the most common problem that people were having. I found a few different ways to approach this problem, depending on your requirments.

   // you can explicitly set an element to show, 
   // prior to applying the scroll pane
    
   $(element).show().jScrollPane();

   OR

   // you can set the visibility to hidden, which leaves the
   // full element in the rendered page, then apply the 
   // scroll pane. After that, you can show/hide the element
   // as necessary. NB: you must reset the visibilty
    
   $(element).css('visibility', 'hidden')
   	.jScrollPane()
   	.hide()
   	.css('visibility', 'visible');

   Unfortunately I didn’t keep track of where I found these solutions, so please leave a comment if this solution is yours and I will give credit where credit is due.

3. You may need to apply the scroll pane after the window is loaded, not just the document

   I found that when a particular div that I was using the jScrollPane on had a lot of images, using code like this:

   $(document).ready(function() {
    
   	$(element).jScrollPane();
    
   });

   would lead to only part of the content being considered scrollable, while the rest of the content was hidden. The reason here, was that the jScrollPane was calculating the height of the scrollable area, prior to the images being loaded in the div. Since the height of the images is part of what determines the final height of the div, the jScrollPane needs to be applied after the images have loaded. This is why it would load correctly when viewing a page that Firefox had already cached the images for, while doing a shift+reload (which does not use the cache) was causing only part of the content to show. My solution for this was to apply the jScrollPane once the window has loaded

   $(window).load(function() {
    
   	$(element).jScrollPane();
    
   });

   NB: depending on how long it takes for your entire page to load, you may notice some delay between the content being rendered and the scroll bars appearing. This can likely be alleviated by displaying a loading sequence until the window.load() method is called.

Hopefully these 3 points will help you avoid some common pitfalls!