jQuery slimScroll

What is slimScroll?

slimScroll is a small (4.6KB) jQuery plugin that transforms any div into a scrollable area with a nice scrollbar - similar to the one Facebook and Google started using in their products recently. slimScroll doesn't occupy any visual space as it only appears on a user initiated mouse-over. User can drag the scrollbar or use mouse-wheel to change the scroll value.

Download

You can download latest stable version in zip (v1.3.0) from here: slimScroll download.

Alternatively, you can also check out latest build at my GitHub repo.

Any feedback is more than welcome, I'd love to see how plugin behaves on different websites.

Set up

You need need to add jQuery to your website. If you are not it already, you can reference itstraight from super-fast Google CDN:

<script type="text/javascript" src="https://ajax.googleapis.com/ajax/libs/jquery/1.9.0/jquery.min.js"></script>

And then, reference to the slimScroll itself:

<script type="text/javascript" src="libs/jquery.slimscroll.min.js"></script>

After adding a reference to the jQuery, you can use following code to enable slimScroll on your element or elements. Remember to wrap it in document.onload function, so code is called when DOM is ready.

Example, required html structure:


Code to attach slimScroll:

$(function(){
	$('#inner-content-div').slimScroll({
		height: '250px'
	});
});

Examples

Below are few examples of the possible configuration. Mouse-over the div to make scrollbar appear.

			  $('#slimtest1').slimScroll({
				  height: '200px'
			  });
	$('#slimtest2').slimScroll({
		position: 'left',
		height: '150px',
		railVisible: true,
		alwaysVisible: true
	});
			  $('#slimtest3').slimScroll({
				  color: '#00f',
				  size: '10px',
				  height: '180px',
				  alwaysVisible: true
			  });

Documentation

Basic configuration

 $(selector).slimScroll();

Example of additional settings

$(selector).slimScroll({
    width: '300px',
    height: '500px',
    size: '10px',
    position: 'left',
    color: '#ffcc00',
    alwaysVisible: true,
    distance: '20px',
    start: $('#child_image_element'),
    railVisible: true,
    railColor: '#222',
    railOpacity: 0.3,
    wheelStep: 10,
    allowPageScroll: false,
    disableFadeOut: false
});

width - Width in pixels of the visible scroll area. Stretch-to-parent if not set. Default: none

height - Height in pixels of the visible scroll area. Also supports auto to set the height to same as parent container. Default: 250px

size - Width in pixels of the scrollbar. Default: 7px

position - left or right. Sets the position of the scrollbar. Default: right

color - Color in hex of the scrollbar. Default: #000000

alwaysVisible - Disables scrollbar hide. Default: false

distance - Distance in pixels from the edge of the parent element where scrollbar should appear. It is used together with position property. Default:1px

start - top or bottom or $(selector) - defines initial position of the scrollbar. When set to bottom it automatically scrolls to the bottom of the scrollable container. When HTML element is passed, slimScroll defaults to offsetTop of this element. Default: top.

wheelStep - Integer value for mouse wheel delta. Default: 20

railVisible - Enables scrollbar rail. Default: false

railColor - Sets scrollbar rail color, Default: #333333

railOpacity - Sets scrollbar rail opacity. Default: 0.2

allowPageScroll - Checks if mouse wheel should scroll page when bar reaches top or bottom of the container. When set to true is scrolls the page.Default: false

scrollTo - Jumps to the specified scroll value. Can be called on any element with slimScroll already enabled. Example: $(element).slimScroll({ scrollTo: '50px' });

scrollBy - Increases/decreases current scroll value by specified amount (positive or negative). Can be called on any element with slimScroll already enabled. Example: $(element).slimScroll({ scrollBy: '60px' });

disableFadeOut - Disables scrollbar auto fade. When set to true scrollbar doesn't disappear after some time when mouse is over the slimscroll div.Default: false

touchScrollStep - Allows to set different sensitivity for touch scroll events. Negative number inverts scroll direction.Default: 200

Events

slimScroll publishes slimscroll event when scrollbar reaches top or bottom of the parent container. You can use jQuery bind method to subscribe to this event:

 $(selector).slimScroll().bind('slimscroll', function(e, pos){
     console.log("Reached " + pos");
 });
Please note: Since version 1.0.0 scroll() option has been deprecated and replaced by more functional scrollTo and scrollBy. Additionally, plugin file name has been changed from slimScroll.js to jquery.slimscroll.js. Take care when upgrading!
Love slimScroll?
Buy me a coffee!


Comments

Hi Piotr,

Thanks for this great plugin. It is very simple, and useful.
I have just 1 comment what is pointed in the subject.

I have tried to solve the problem, but until now without any results.

--
István

thanks István, I will investigate this issue ASAP.

hey István, I updated my plugin. I tested it on IE8 and it works fine now so hopefully IE9 should work as well.

Hi Piotr,

Thanks for the quick response.
I will try it after work.

It works. Thanks.

It actually works in IE9.

The problem comes from this page and how the plugin javascript file is referenced.
It is referenced from GitHub, but GitHub serves the .js file as "text/plain" and not "text/javascript" MIME type.
IE9 considers this as a security problem and does not load the script file.

thanks Didier! I missed that. I tested it in IE9 but never when linked from github. I'll fix it soon.

Hey, I updated my article page to load it from my own server and not from github. It should be behaving ok on IE now.

hi,

i had a problem when the user was resizing the window ( the slimscroll was applied to a div that depends of viewport size ) . So i invented a way to update scrollbars during a resize event without creating a new one.

Mys solution to this problem :
var resizeHandler = function(element, scroll_id) {
var me = $(element);
me.css("height",$(window).height()+'px');
$(".slimScrollDiv"+scroll_id+"").css("height",$(window).height()+'px');
var height = Math.max((me.outerHeight() / me[0].scrollHeight)
* me.outerHeight(), 30);
$(".slimScrollBar"+scroll_id+"").css({ height: height + 'px' });
}
element is the variable used when you do $(element).slimScrol([...]);

Also i had a problem with multiscrollbars ( when ressinzing the window ) so i created a way to resize each of these scrollbar independently. My solution was to create a counter for each slimscroll applied.

Little error in the given script :
var resizeHandler = function(element) {
var me = $(element);
me.css("height",$(window).height()+'px');
$(".slimScrollDiv").css("height",$(window).height()+'px');
var height = Math.max((me.outerHeight() / me[0].scrollHeight)
* me.outerHeight(), 30);
$(".slimScrollBar").css({ height: height + 'px' });
}

Thanks Benjamin, this is a really good idea. Scrollbar adjusting to the changing size of the container makes perfect sense. I will add this feature in the upcoming patch.

Has this been implemented? Essentially the way the script can take the parent width if applied to the height would achieve this functionality. Is that correct?

If there are more than one slimScrolls in a page, if Im not wrong, the above script will apply the same height to ALL scroll regions (since we are applying height property by class [$(".slimScrollBar")], not by ID). Is there a way to refer just that particular scroll region and re-apply height?

Hi,
I managed to resolve the glitch I reported when re-applying height property to $(".slimScrollBar") (Benjamin's idea). That will re-apply height to ALL slimScroll regions in the page; Benjamin, Im not sure if I understood your solution correctly, but you can confirm on this.

Anyways, you can try this:

STEP 1:
--------
While instantiating slimScroll, pass an extra parameter "id" with some value
$('#dvScrollTest').slimScroll({
id: 'dvScrollTest',
size: '5px'
});

STEP 2:
--------
In the source file (version 0.5.0), apply a class to the wrapper DIV (divS) used for bar,rail etc.
NOTE: make use of the "id" parameter and apply different class name to each scroll region (I have used the prefix "clsSlim_" for class name)

// do it for every element that matches selector
this.each(function(){
...
divS = "<div class='clsSlim_" + o.id + "'></div>",

STEP 3:
--------
Now, when you want to resize slimScroll (to follow its parent's changed height), simply re-apply the height property for wrapper DIV:

$(".clsSlim_dvScrollTest").css("height",$('#dvScrollTest').height() + 'px');

Hope its of use to someone. Thanks.

I know the id & parent of the object is container.

$('#inner-content-div').parent().css({ height: w_height });
$('#inner-content-div').css({ height: w_height });

It looks like you can pass the wrapperClass as param when initiating slimscroll (which, btw, fits great on my website :) ).

I noticed this bug when I tried to use it on 2 containers of different height and it adjusted all of them... so, what I did was this: instead of passing the wrapperClass as param, I generated it randomly when initiating the scroller.

jQuery.fn.extend({
slimScroll: function(options) {
var dateTime = new Date();
var wRand = dateTime.getMilliseconds();

var defaults = {
// a couple of lines later...

// defautlt CSS class of the slimscroll wrapper
wrapperClass : 'slimScrollDivRand' + wRand,

This solved the problem for me. I don't know how it affects memory usage, I haven't tested it yet, but I guess it won't make a big difference :)

How to apply a class to the wrapper DIV (divS) ?
Can you send a little example?
I'm not very good on jQuery.

kindly explain this code for the beginner.
Where to add this code?

<body onresize="window.location=window.location">

Hi Piotr,

Thanks for the plugin. Your demo on this page works sleek in Chrome, however, it doesn't work on IE8, and IE9.. so probably you'd need to update your code somewhere.

Thanks,
Totti

Hey Totti, thanks for your comment.
Can you specify what exactly doesn't work? I just checked this demo on IE8 and it works fine. (Well, rounded corners from scrollbars are missing, but this is known limitation of Internet Explorer). Everything else - scrolling, fade in/fade out, mouse-wheel scroll and so on is ok.

It works on IE8 & 9 , just need to use the original code , not minified ( that was my solution )

Hey, I checked the minified version and even set up a test case here: http://rocha.la/misc/jsdemos/slimScroll/index.min.htm - everything works fine on IE8 (at least on my pc).

What sort of issues do you see?

First of all, great work you're made with slimscroll.
Now, talking about the problem, I've implemented it in a webpage and it works very well, except that in IE9 the scroll just works with the mouse scroll, it doesn't work dragging the bar with the mouse.
On your test case, works for me in every browser, but on IE9 it doesn't display the scrollbars at all, just plain text on the page and nothing more.

IE9 tries to execute the inline script at the end of your index.htm before parsing slimScroll.min.js.
Move that piece of code to window.onload.

Hey,
at first its a great plugin.
I try to use it with a div that has a float: left. But if I use the plugin the float does no longer work.
Can u tell me what I do wrong.

Hi Ronny,

I will have a look into it, but for now, you could create inner div that holds scrollable content, so for example:

.. text.. to.. scroll...

Where #news is your div with float and #news_content is div where you apply $('#news_content').slimScroll();

Hi there,

I really like the plugin, however I cannot seem to get it to function on my website. I am fairly new to code and totally self taught. Here is is where I have used it - http://www.lilyemo.co.nz/work/honouringAMprayer.html, what have I done wrong?

Hey,

I've noticed that you are missing jQuery Draggable. Add this code to the header of your website, immediately after you load jQuery:

(Or you could just download it yourself from jQuery website, but loading it from Google CDN is easier and faster.)

It works great now, thank you!

I'm here just to congrat you for the wonderful job you've done!
I really loved it!

Regards, Marcos Gonçalves

Thanks a lot Marcos! I'm glad you like it. Feel free to post a link to your website and show off what you've done with it! :)

Hey
I've just tested this plugin and already love it. Great job! Finally no more nasty, ugly scrollbars when making only a part of a site scrollable.
There's just one point i'm missing:
Is it possible in any way to get some space between the scrolling div (or whatever you use) and the scrollbar?

ps: i'm using it on a position:absolute <div>, padding didn't help

Could I also suggest this please

Also should the scroller detect if it is needed or not? On my site it appears even if the content doesnt need to scroll

You can see the effect here (and you can see the bar working on the about us page)

Site is an ongoing project so may change

Lee

Paste fail http://virtualdirection.com/index.php#morestuff

Hey Lee, good point. I will patch it in the next version.

Super :) It would be great.

Super. Ver. 0.2.4 works perfect. Thank you very much for your work.

Hi

Is it possible to add the scroller to all elements with a specific selector. I tried and it doesnt show the scroller?

Thanks

Lee

Hi Lee,

Thanks for spotting this defect. I have updated my plugin. Please download newest version - v0.2.3 and you will be able to use $('.className') selector to attach the slimScroll to multiple elements at once.

Thats working on all elements now

As commented earlier, should the scroller be showing up on elements that dont need to scroll? Is it possible to check this, so the scroller is disabled if the content is not larger than the div?

Thanks

Lee

every time i add a <ul> element, the scroll stops working.
any fix?

Hi there,

Love the scroller! However, does anybody have any simple amends to this code that would update the scroller depending on variable div content, similar to Benjamin B's solution for viewport size?

Thanks.

Hi James, I've seen someone already submitted fix to my github repo tackling this issue. I'll review and create new release.

I'm using the latest from github, and the scrollbar doesn't seem to update itself with the content. Is there an option that needs to be set?

I've added little mod.
When content is smaller than container - slider sholdn't appear. So I added one line in your code:

var height = Math.max((me.outerHeight() / me[0].scrollHeight) * me.outerHeight(), minBarHeight);

if (height+"px"==cheight) { height = 0 } //added line

bar.css({ height: height + 'px' });

hey qczy,
good news - this fix has been already added in the latest release. Download version 0.2.4 from github or jQuery Plugins page and you shouldn't see the scrollbar anymore when content is not long enough.

When using 'alwaysVisible: true' to prevent slider from hiding it still shows full-height slider

adding:

if(barHeight==me[0].scrollHeight) { barHeight = 0 }

in 236 line of new ver (0.4.3) will do the job.

by the way - some flattering stuff - good plugin

Pages

Comment

Plain text

  • No HTML tags allowed.
  • Lines and paragraphs break automatically.
CAPTCHA
This question is for testing whether you are a human visitor and to prevent automated spam submissions.

Check out my latest game!

Android app on Google Play

Recent comments