Need some help?

I'm usually available for small jobs or problem solving with jQuery or css, at reasonable rates. Just get in touch.

Web Hosting

We recommend Clook for web hosting. UK based, great service and great value.

Buy me a drink

If you've found this useful, particularly for commercial projects, you might consider making a small donation.

Vertical scrollbar plugin using jQuery UI slider

This plugin wraps up a number of the variants of my jQuery vertical scrollbar. Specifically this plugin supports:

  • Multiple sliders on one page
  • Scrolling with a mousewheel
  • The use of images for scrollbar handles
  • The size of the scrolled content changing after load (through AJAX for example)
  • Customisation via css

I’ve tested this in FF7, IE6, IE7, IE8, Chrome, Safari 5 and Opera 11, all on Windows 7, using jQuery 1.7.1 and jQuery UI 1.8.14.

View a demo here.

Setup

This plugin requires jQuery and jQuery UI, so you need to load these and the plugin into in your head, plus the css file. Optionally, you can load Brendan Aaron’s mousewheel plugin as well. Then, assuming you have stored the javascript files in a folder in your root file called javascript, and the css file in a folder in your root file called css, then you should have something like this:

<script type="text/javascript" src="http://ajax.googleapis.com/ajax/libs/jquery/1.7.1/jquery.min.js"></script>
<script type="text/javascript" src="http://ajax.googleapis.com/ajax/libs/jqueryui/1.8.14/jquery-ui.min.js"></script>
<script type="text/javascript" src="/javascript/jquery.sbscroller.js"></script>
<script type="text/javascript" src="/javascript/jquery.mousewheel.min.3.0.6.js"></script>
<link rel="stylesheet" href="/css/jquery.sbscroller.css" />

The plugin will add a scrollbar to a selected element which has a fixed height and content which exceeds that height. The scrollbar will be placed on the right hand side of the scrolled element using position:absolute. At the moment this means the scrollbar must be within the parent scrolling element, as I thought this might be more convenient. If anyone is interested it would be possible to add an option to position the scrollbar outside the scrolling element, let me know…

Configuration

All you need for the basic scrollbar is this, placed before the closing </body> tag – where #myelement is replaced by your element selector, obviously:

<script type="text/javascript">
$('#myelement').sbscroller();
</script>

Options

To set an option, the name, followed by a colon, followed by the required value as shown below, all wrapped in curly brackets {}, needs to be entered in the round brackets after sbscroller. Separate multiple settings with a comma. See below for some examples. Different scrollers on the same page may be set up with different options.

Option Description Example values Default value
handleImage A string setting the path of the image to be used as a background-image on the slider handle, which will be set to repeat-y. ‘/images/handleimage.jpg’ false
handleTopImage A string setting the path of the image to be added to the slider handle, and positioned at the top of the handle. ‘/images/handletop.jpg’ false
handleBottomImage A string setting the path of the image to be added to the slider handle, and positioned at the bottom of the handle. ‘/images/handlebottom.jpg’ false
handleGripImage A string setting the path of the image to be added to the slider handle, and positioned at the vertical centre of the handle. ‘/images/handlegrip.jpg’ false
autohide A Boolean setting the scrollbar to dispay only when the scrolling element is hovered. true (note no quotes, this is a Boolean not a string) false

An example with all options set:

$('#myelement').sbscroller({
				handleImage:'/images/misc/scrollbar-handle-middle.png',
				handleTopImage:'/images/misc/scrollbar-handle-top.png',
				handleBottomImage:'/images/misc/scrollbar-handle-bottom.png',
				handleGripImage:'/images/misc/scrollbar-handle-grip.png',
				autohide:true
});

Mousewheel support

The plugin automatically supports Brandon Aaron’s mousewheel plugin. If the plugin is present, the mousewheel can be used to scroll. Thanks to Dimitris for this suggestion.

Methods

The plugin supports two methods:

Method Description Usage
refresh Refreshes the slider. This can be called after content has been added or removed from the scrolling element, after a hidden scrolling element is displayed, or for any other reason. $('#myelement').sbscroller('refresh');
reset Resets the slider to the initial state, with the scrollbar at the top $('#myelement').sbscroller('reset');

Customisation

The background to the slider and slider handle are set as a default in the css as a light grey and dark grey respectively – you can change these using css, and also change the width of the slider if you wish.

Changelog

V1.2 – 9 January 2012 – Mousewheel code amended to allow for repeated show/hide of hidden elements, and to alter the scroll speed dependent on the height of the scrolled element (as opposed to moving a fixed percentage).

V1.3 – 9 January 2012 – Mousewheel code amended to run automatically if mousewheel plugin is present, mousewheel option removed.

V1.4 – 17 January 2012 – Amended to cope with the height of the scroll pane being changed – thanks to JustPie for pointing this omission out.

V1.5 – 12 February 2012 – Amended to cater for the ‘refresh’ being called when the scroller has not previously been set – the code now tests this and sets up the scroller if it doesn’t exist.

V1.6 – 6 March 2012 – Removed the unnecessary wrap with .scroll-container (this was a legacy of floating the scrollbar instead of using absolute position).

V1.7 – 5 September 2012 – Added a reset method.

V1.8 – 12 November 2012 – Corrected a typo in the script affecting the handleImage option.

V1.9 – 29 January 2013 – Amended code to cope with non-html content in the scrolled element option.

Download

Zip file containing javascript and css files (4kB)

Can I use this on my site?

Probably. See my policies on using code from this site.

Don’t link directly to the files on this site – that eats up my bandwidth. Create a copy on your own server.

Using the plugin with touchscreens

As it stands, this will not work with touch screens as jQuery UI does not itself support touch events. I have done only limited testing on an iPad, but TouchPunch seems to address this nicely. Just include it on your page. Don’t currently have access to a touchscreen device, so if you do use TouchPunch, let me know how you get on.

Using the plugin with jQuery UI css

This plugin cannot be styled directly using the jQuery UI css themes – the images supplied do not work well with a vertical, as opposed to horizontal slider, and the vertical slider requires an additional enclosing element for the slider, with the result that the wrong element is styled. However, it should be pretty straightforward to adapt your css to pick up the jQuery UI css styles if required. You can find an example which replicates the ui-lightness theme here.

Linked to this, if you are using jQuery UI css on your page as well as sbscroller.css then there is some interference between the two. This can be overcome by some additions to sbscroller.css which you can download here (1kB). If you’re not using images for the handle you also need to set the background-image to none on .ui-slider-handle.

Using the plugin with WordPress

If you want to use this in WordPress, then the recommended way of adding all the scripts is to add the following to your functions.php:

function sb_scroller_scripts() {
    wp_enqueue_script( 'jquery' );
	wp_register_script( 'jqueryui', 'http://ajax.googleapis.com/ajax/libs/jqueryui/1.8.14/jquery-ui.min.js');
    wp_enqueue_script( 'jqueryui' );
	wp_register_script( 'sbscroller', get_template_directory_uri().'/js/jquery.sbscroller.js');
    wp_enqueue_script( 'sbscroller' );
	wp_register_style('sbscrollercss',get_template_directory_uri().'/jquery.sbscroller.css');
	wp_enqueue_style('sbscrollercss');
}    

add_action('wp_enqueue_scripts', 'sb_scroller_scripts');

This assumes you have jquery.sbscroller.js in your templates file and jquery.sbscroller.js in a subfolder called js. If you’ve already got jQuery loaded you don’t need the first line. This will load all the jQuery files and the css file in your header. You can also manually edit your header.php to include the files.

Then on the page you want the scroller to appear, add the following via the html tab:

<script type="text/javascript">
jQuery('#myelement').sbscroller();
</script>

Note that you have to use jQuery in full here since WordPress applies jQuery.noConflict() by default, which means the $ shortcut won’t work.

72 responses to “Vertical scrollbar plugin using jQuery UI slider”

  1. jeroen says:

    hello,

    I want to use your jquery plugin to customize the scroll-bars of a div. but I can’t get it to work. What do I surely have to put in the css code of my div ‘updates’ where I want scroll bars??

    Thanks

  2. Simon says:

    Jeroen

    Not sure if that is a real email address otherwise I would have sent you a mail. You shouldn’t need to add any css other than the file that comes with the plugin.
    If it’s still not working can you send me a link, because otherwise I’m only guessing….

  3. Wu Chia Chong says:

    What should I write in my HTML, and what kind of ID should I use to the HTML element in order to use this plugin?

  4. Simon says:

    Your html can be pretty much anything you want – your container element (normally a div) needs to have a fixed height, and the content that you want to scroll obviously needs to be within that html element. It doesn’t matter what id or class you apply to your chosen element – you can use that to identify the element and apply the . sbscroller method in the same way as any other jQuery method.

  5. dimitris says:

    i was seriously going nuts trying to make this work (ui slider as vertical scrollbar), nice work, thanks…
    it even fits my need to scroll a previously hidden element:)

    one suggestion… you could tweak so you don’t need a mousewheel option very easily, just replace
    if(settings.mousewheel){
    with
    if($.fn.mousewheel){
    and when mousewheel is available it is “auto-detected”

  6. Marci says:

    The mouse scrolling speed is dependant on the content. So if there is a lot of content the scrolling is incredibly fast, and if the content is just a little bigger than the container than the scrolling is very slow.

    Can you help me find a way to make the mouse scrolling speed constant (independent of the content length)?

  7. Simon says:

    This amendment is included in V1.2.

  8. MarkS says:

    How can I position the scrollbar at the bottom after a ‘refresh’?

  9. Simon says:

    You could do this by using .find('.slider-vertical').slider("value", 0); on the scrolled element.

  10. JustPie says:

    I noticed that the scrollbar doesn’t resize correctly if you resize the parent element. This can be fixed by removing moving line 67: ” $scrollpane.find(‘.slider-wrap’).height(Math.round($scrollpane.height())); ” outside of the scope of the if statment that its currently in.

    Hope this helps someone out.

  11. Simon says:

    Thanks for pointing this out. I have amended the plugin to cope with this – version 1.4.

  12. John says:

    I am wondering if this plugin has support for touch devices ?

  13. Simon says:

    I haven’t tested it myself on a mobile device. The issue is really whether jQuery UI works consistently on mobile devices – I suspect the answer is no at present.

  14. marc fawzi says:

    hey there!

    I bet you use Chrome to test because it works well on Chrome.

    But on Firefox 10.0 (and previous versions), when you do a fast scroll-up on the touchpad (Macbook) when the scrollbar is at the top-most position then you should see some very crazy jittering… Normally. jQuery slider doesn’t work with mousewheel events so I assume you added that and so the bug is either in the mousewheel plugin or your code, but I’d think in the former.

    Try it out yourself and see..

    Marc

  15. Simon says:

    Marc

    I tested on FF, Chrome, Opera, Safari and IE6+, as it says on the plugin page. I don’t see the behaviour you describe on FF10 on W7, so it may be restricted to Mac.

  16. Smartboy says:

    @John:
    Jquery-ui doesn’t support touch devices as of the latest version, but there are libraries out there such as jquery.ui.touch-punch.js which add the compatibility into jquery-ui. However, I think it’d be better to use Jquery Mobile since that seems to be what is better supported on touch-capable devices.

  17. MOCK says:

    If you have a trouble with mousewheel event (jQuery 1.7.+), you can fix it. Just replace:
    if ( event.detail ) { delta = -event.detail/3; }

    to

    if ( event.originalEvent.detail ) { delta = -event.originalEvent.detail/3; }

  18. Simon says:

    I don’t see a problem with the mousewheel myself.

  19. JeBuS says:

    Is it possible to get your plugin to use the jQuery UI theme? It would be nice if your scrollbar looked like the ui-slider.

  20. Simon says:

    I’ll have a look at this sometime in the next week or so.

    I’ve had a quick look at this. There are two major issues with using the jQuery UI css. First, the images that jQuery UI css uses for the slider handle background are designed for a horizontal slider, not a vertical one, so they don’t work well. Secondly, jQuery UI css applies images to the background of the .ui-slider element, which does not extend to the top and bottom of my scrollbar (instead you would need to style its parent element .slider-wrap.

    Major changes would be required to resolve these, which frankly don’t seem worthwhile to me. It’s simple enough to amend your css to replicate the style of the jQuery UI css.

    Related to this, if the jQuery UI css is used on the same page as sbscroller.css then there is some interference. The following amendments to sbscroller.css should overcome this:

    .scroll-content {position:absolute;top:0;left:0;padding-right:20px}
    .scroll-pane{position:relative;}
    .slider-wrap{position:absolute;right:0;top:0;background-color:lightgrey;width:20px;}
    .slider-vertical{position:relative;height:100%;background:none !important;border:none !important}
    .ui-slider-handle{background-color:darkgray;width:20px !important;height:10px;margin:0 auto;display:block;position:absolute;border:none !important;left:0 !important}
    .ui-slider-handle img{border:none}
    .scrollbar-top{position:absolute;top:0;}
    .scrollbar-bottom{position:absolute;bottom:0;}
    .scrollbar-grip{position:absolute;top:50%;}
  21. Ann says:

    Hi Simon,

    Love your script it was so easy to plugin! One question: Is there a way to change the height of the scrollbar so that it is shorter than the element that is being scrolled?

    Thanks,
    Ann

  22. Ann says:

    Hi Simon,

    Got the scroller to fit where I wanted it to! Thanks so much, I donated a couple of drinks for you!

    Cheers,
    Ann

  23. JustPie says:

    I have made a few improvements / bug fixes to the plugin. I commented all changes.

    http://pastebin.com/yhEYQDk8

  24. Simon says:

    JustPie

    Thanks for your interest (again). Re the mousewheel issues if the slider is refreshed, I’ve already fixed this in version 1.2 by simply removing the mousewheel and re-instantiating it. Moving the mousewheel code outside setSlider() will work, but the mousewheel scrolling will not change to reflect any change in height of the scroll pane.

  25. Julian Josephs says:

    How do I make the content in the plugin autoscroll on page load and reset to the first element when I reach the last.

  26. Simon says:

    Julian

    The plugin doesn’t support autoscroll – but if you have a look here I have a non-plugin version that might do what you want.
    View the source to see how it’s done.

  27. Harry says:

    Hi Simon,

    Really great plugin that we’re starting with! We have an element that changes height depending on the amount of text. Previously, we had no fixed height and it would add the (old) scroll only if the max height was reached. Is there a way to use your scroll without a fixed height because now we cannot dynamically change the height?

    Cheers!

  28. Simon says:

    Harry

    I think in fact you’ve answered your own question – if you assign a max-height rather than a height to the div, then no scrollbar is created if it’s not needed, and if the content exceeds the max-height then a scrollbar is set up.

  29. mumi says:

    nice plugin, but i have some problems with an mobile approach, nowadays those pluins should work with touch and swipe events…
    i just wrote in the plugin using the touchwipe plugin.. but the target data has problems… and wont scroll…

  30. Simon says:

    Hi Mummi

    Yes, the plugin doesn’t support touch devices currently.

  31. marc says:

    Hi,
    how do I specify a javascript callback to be executed with the “onscroll” event?

  32. Simon says:

    Marc

    Best to trigger this via the stop or maybe the slide event which jQuery UI slider supports – see here for details.

  33. Jeroen says:

    Is there an option to move the scrollbar back to top, this would be helpfull in a jquery tabs setup after reopening a previous tab with a changend scrollbar position.

  34. Simon says:

    Jeroen

    I’ve added this as an additional method to the plugin – see the page for details.

  35. mumi says:

    i ve added a touhc functionality to the plugin, using the touchwipe plugin, its really simplified, for my case, but easily modify-able

    heres my plugincode ->http://jsfiddle.net/DD4Ec/
    ive modifierd the code at the end, it wstarts with wipeScroll if i remember correctly.

  36. amay says:

    how would i add vertical slider on my page?in my div i will have link lists..

  37. Simon says:

    Amay

    Having lists shouldn’t affect how the slider works, pretty much any content enclosed within the scrolled element will be OK.

  38. Bogdan says:

    Could I replace vertical sliders of html combox with tag select? I tried it not work.

  39. Simon says:

    Bogdan

    I don’t understand what you mean I’m afraid.

  40. Roman says:

    Hi!

    I try to use this script in a WordPress project. I add it this way:
    function scroller(){
    wp_enqueue_script (‘vertscroller’, get_bloginfo(‘template_directory’).’/scroller/jquery.sbscroller.js’, array(‘jquery’,’jquery-ui-core’), false, false);
    }
    add_actions(‘wp_enqueue_scripts’,’scroller’);

    and on the page I get a javascript error:

    ‘undefined’ is not a function evaluating ($scrollpane.find(‘slider-vertical’).slider’)

    it’s on line 79 of jquery.sbscroller.js

    what could it be? can I somehow fix it?

  41. Simon says:

    Roman

    The error message suggests you might not have jQuery UI loaded – this is needed as well as jQuery.

  42. Roman says:

    the “jquery.ui.core.min.js” is loaded. It’s a dependancy for the scroller script (see the line with wp_enqueue_sript, i.e. array(‘jquery’,’jquery-ui-core’)). I’ve just checked the page — yes, it is there.

    If that’s not enough, perhaps you could tell me what “modules” of jQuery UI should I load?

  43. Simon says:

    You need Slider as well as core. Personally, I find it easiest to link to the Google CDN for jQuery UI.

  44. Roman says:

    I added ‘jquery-ui-slider’ as a dependency and it worked.

  45. Jeremy says:

    Apparently, the css rule display: none on the target element prevents the sbscroller to exist. You have to make it visible at load and hide it by JS to make sbscroller work properly

  46. Simon says:

    Jeremy

    Yes, if the element is hidden it has no height and no scroller is created.
    If you call the refresh method when the element is un-hidden, then the scrolbar will be created correctly.

  47. Jeremy says:

    Thx, logical, for sure.

    Another thing:
    When using mousewheel to browse your sbscroller, if the page itself has a (native) scrollbar, it’s scrolling also, at a lower speed than the sbscroller.

    This behaviour is related to new event wheel introduced in FF 17:
    https://github.com/brandonaaron/jquery-mousewheel/issues/45

    You have to beautify (unminify) jquery.mousewheel.3.0.6.min.js and change line 21 from
    var b = [“DOMMouseScroll”, “mousewheel”];
    to
    var b = [“DOMMouseScroll”, “mousewheel”, “wheel”];

    Tested in Chrome and FF17, and seems to work

  48. Simon says:

    Thanks Jeremy
    For info to others, I cannot currently replicate this behaviour using FF17.0.1.

  49. suricactus says:

    Hello. Great job with the plugin. There is one very minor bug, on lines 24 and 36 you should use `.contents()` method, instead of `.children()`. If the contents aren’t html tags, there is some weird misbehavior. Also minified version of this excellent plugin is a must. 🙂

  50. Simon says:

    Thanks for your comments. I’ve amended the plugin per your suggestion – this hasn’t come up as an issue before. Minified? Well, it’s currently 8kB, so marginal savings by minifying, and I think, outweighed by the benefit of having readable code. Cheers though!

  51. Asim says:

    Hello Simon

    thanks. you have created a great scroll bar plug in. I wish to use it on my live site. Is there anything i can do for it.

    have a nice day
    Asim

  52. Simon says:

    Do you mean can you use it on your own site? Yes, you can.

  53. Asim says:

    Thankypu Simon
    basically its for client site, i m creating it,

  54. Simon says:

    If it’s for a client site, for which you’re being paid, then a small donation is appreciated.

  55. asim says:

    basically i am working with a development company.
    and i need an alternative for default scroll bar.
    how can i make donation

  56. Simon says:

    Thanks – use the ‘Buy me a drink’ button on the left hand side.

  57. Alex says:

    Great plugin, but I found a little bug (testet with Chrome and Opera).
    Try to search something, that isn’t in the visible area.
    For example search “15” (with STRG+F) on the demo-page.

  58. Simon says:

    Alex

    Yes, good spot. I don’t think this can be fixed as you’d need to trap the browser search event to do so, and this would be very bad practice.
    This discussion covers some of the reasons why.

  59. Alex says:

    You could trigger it with .scroll().
    http://api.jquery.com/scroll/

    $(‘.scrollpane’).scroll(function() {
    alert(‘trigger’);
    });

    It works very good. I tested it.

  60. Simon says:

    That doesn’t work in Firefox unfortunately, and seems hit and miss in Safari.
    I’ve looked at this before where a user had a form within the scroll area and was navigating down it by tabbing. Although in this case I could reliably capture the event, there was no way of reliably establishing the resulting scroll position and reestablishing the scrollbar, and I suspect the same is true here.

  61. Alex says:

    But Firefox and Safari don’t find objects in non-visible areas. So the problem only occurs with Chrome, Opera and IE. I search for “15” (demo example), the browser automatically scrolls down and it triggers.

    If I search with Firefox and Safari nothing happens. It doesn’t find the “15”. It doesn’t scroll down automatically. No bug, so no need to trigger and fix.

    The trigger works as it should. Only establishing the scroll position may be difficult.

    The following code does the trick, but it’s not optimal 😉
    $(‘.scrollpane’).scroll(function() {
    $(‘#scrollpane1’).sbscroller(‘refresh’);
    });

  62. Simon says:

    Yes, almost, seems OK in Chrome, Safari and Opera, but something slightly different happens in IE. Don’t have time to look in depth at the moment, but I will investigate at some point.

  63. DorT says:

    I really love this, but I’m having a ton of issues with the mousewheel.

    Any suggestions regarding the latest version?

  64. Simon says:

    The latest version of the mousewheel code or the latest version of jQuery? If the latter this comment from Dirk Kirkland (actually on the non-plugin version) may help.

  65. Bostjan says:

    Hi,

    I have a problem on mobile phones. The .scroll-content div is not resizing past a certain height so the scroller only shows part of the text. Example can be seen here: http://sibincic.bobr.si/podrocje-dela.php

    Any idea what could be causing it?

  66. Simon says:

    I’m not seeing that on iPhone/Safari. To be honest the slider doesn’t work well with touch screens in any case.

  67. Barna Szalai says:

    Hi, I use the vertical plugin, but the scrollbar gets constantly wrong height value, when I press F5 more times. More exactly , the .slider-vertical div has changing height, and top-margin values, even the content is fixed, doesn’t change. What should I check in my code to correct this behaviour? Eg. 5 times has the correct value, but the 6th time has lower height, and higher top-margin value.
    Thanks

  68. Simon says:

    Hello Barna
    I can’t recreate this at all, and I’ve had no other reports of this. Can you give a link to your page?

    UPDATE FOR OTHERS: The problem manifested only in Chrome, and is caused because Chrome (Webkit) calculates div heights without images at $(document).ready(), giving unexpected behaviour in this case. The solution is either to delay setting up the slider until $(window).load() or to fire a refresh at this point.

  69. rusia says:

    love this! thx so much for the work!
    i was wondering how this can work on a wordpress theme. I have one that I want to use but the columns on the landing page are fixed and I would rather have it scroll so folks dont have to click anything to see extra content. just want them to scroll.
    thanks in advance

  70. Simon says:

    You can just add the code directly into your template if you need to, or have a look at the section about WordPress at the bottom of this page.

  71. Stefan Höhn says:

    tried it with jquery 1.10.2 and unfortunately it does not work with that version (I am aware that the spec above says jquery 1.7.1). Just to let anyone know how also tries.

  72. Simon says:

    Stefan
    It works fine with jQuery 1.10.2 and jQuery UI 1.11.2 – I have updated the demo. You may have been using incompatible versions of jQuery and jQuery UI.

Useful? Interesting? Leave me a comment

I've yet to find a way of allowing code snippets to be pasted into Wordpress comments - so if you're trying to do this you'd be better off using the contact form.