jQuery slimScroll

Submitted by Piotr Rochala on Sun, 10/16/2011 - 15:59

What is slimScroll?

slimScroll is a small (3.7KB) 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.1.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

For plugin to work, you need add reference to jQuery and jQuery UI (Draggable) to your website. If you are not running these libraries already, you can reference them straight from super-fast Google CDN:

<script type="text/javascript" src="https://ajax.googleapis.com/ajax/libs/jquery/1.9.0/jquery.min.js"></script>
<script type="text/javascript" src="http://ajax.googleapis.com/ajax/libs/jqueryui/1.10.1/jquery-ui.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 and jQuery Dragabble, 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:



Lorem ipsum dolor sit amet, consectetur .... snip

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.

Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nam rhoncus, felis interdum condimentum consectetur, nisl libero elementum eros, vehicula congue lacus eros non diam. Cum sociis natoque penatibus et magnis dis parturient montes, nascetur ridiculus mus. Vivamus mauris lorem, lacinia id tempus non, imperdiet et leo. Cras sit amet erat sit amet lacus egestas placerat. Aenean ultricies ultrices mauris ac congue. In vel tortor vel velit tristique tempus ac id nisi. Proin quis lorem velit. Nunc dui dui, blandit a ullamcorper vitae, congue fringilla lectus. Aliquam ultricies malesuada feugiat. Vestibulum placerat turpis et eros lobortis vel semper sapien pulvinar.

Pellentesque rhoncus aliquet porta. Sed vel magna eu turpis pharetra consequat ut vitae lectus. In molestie sollicitudin mi sit amet convallis. Aliquam erat volutpat. Nullam feugiat placerat ipsum eget malesuada. Nulla facilisis nunc non dolor vehicula pretium. Sed dui magna, sodales id pharetra non, ullamcorper eu sapien. Mauris ac consectetur leo. Mauris consequat, lectus ut bibendum pulvinar, leo magna feugiat enim, eu commodo lacus sem vel ante. Sed tempus metus eget leo mollis vulputate. Class aptent taciti sociosqu ad litora torquent per conubia nostra, per inceptos himenaeos.

Cum sociis natoque penatibus et magnis dis parturient montes, nascetur ridiculus mus. Sed pulvinar rhoncus quam, vel semper tellus viverra id. Nulla rutrum porttitor odio, a rutrum purus gravida non. Etiam ac purus augue, eget vestibulum purus. Aenean venenatis ullamcorper augue, non consequat elit tempor sed. Donec velit sapien, volutpat sed ultricies egestas, semper a ante. Fusce dapibus, quam eget auctor suscipit, nibh leo posuere ante, at auctor nisi lacus in sem. Morbi interdum consectetur euismod. Cras accumsan est lacus. Nulla eleifend, eros vel consequat commodo, arcu nunc malesuada nunc, quis sagittis felis sem ac turpis.

Nulla rhoncus elementum convallis. Mauris condimentum aliquet egestas. Ut iaculis nisi eget tellus accumsan venenatis. Maecenas imperdiet aliquam porta. Aenean ultrices dolor sed quam laoreet varius. Curabitur condimentum blandit erat, quis accumsan eros interdum vitae. Curabitur ligula arcu, sollicitudin vitae iaculis sed, blandit sit amet enim. Morbi ullamcorper, metus vel mollis tristique, arcu turpis malesuada nisi, at dignissim lorem odio a orci. Proin ultrices, ipsum ut vestibulum interdum, libero felis auctor mi, vitae convallis nisl justo ac tellus. Integer nec lacinia turpis. Etiam massa nisl, rhoncus quis rutrum in, pretium eu leo. Proin a velit ut nulla laoreet vestibulum. Curabitur eu elit vitae felis auctor tincidunt. Curabitur tincidunt, metus sed sollicitudin cursus, quam elit commodo erat, ut tempor erat sapien vitae velit. Morbi nec viverra erat.

Nullam scelerisque facilisis pretium. Vivamus lectus leo, commodo ac sagittis ac, dictum a mi. Donec quis massa ut libero malesuada commodo in et risus. Fusce nunc dolor, aliquet vel rutrum in, molestie sit amet massa. Aliquam suscipit, justo a commodo condimentum, enim sapien fringilla ante, sed lobortis orci lectus in ante. Donec vel interdum est. Donec placerat cursus lacus, eu ultricies nisl tincidunt a. Fusce libero risus, sagittis eleifend iaculis aliquet, condimentum vitae diam. Suspendisse potenti. Class aptent taciti sociosqu ad litora torquent per conubia nostra, per inceptos himenaeos. Proin leo purus, sodales a venenatis luctus, faucibus ac enim. Sed id metus ac sem lobortis pretium. Mauris faucibus tempor scelerisque. Nunc vulputate interdum tortor, non tincidunt dui condimentum eget. Aenean in porttitor velit. Nam accumsan rhoncus risus id consectetur.

			  $('#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!

Tags:

JavaScript

jQuery

Comments

touch support

Hi. I've downloaded the latest version and i've noticed that it doesn't support touch devices but the one you're using here on this site does. Any comment on that?

Submitted by charles darwin (not verified) on Tue, 10/16/2012 - 07:37

touch

Hi Charles,

On my website im using development snapshot, so it was already running version 0.6.5. Please download the latest version and you'll be able to use slimScroll on the mobile devices.

Submitted by Piotr Rochala on Thu, 10/18/2012 - 18:21

thanks

Hey I forgot to say thank you first

Submitted by charles darwin (not verified) on Tue, 10/16/2012 - 07:38

slimScroll Horizontal Scrolling

The contact link in your footer isn't working. I want to send you a direct email with a bit more detailed description about how I would use see horizontal scrolling with slimScroll on my website. A buddy of mine plans to help develop this code and we'd be happy to donate to you to see this happen. It would be great to see it happen sooner. You'll appreciate the reason I got into horizontal scrolling is from inspiration of Windows 8. Keep it up, Piotr!

Submitted by Brandon James (not verified) on Wed, 10/17/2012 - 21:12

display none is not working

Hi,
due to you cover your elements around the target-div, the scrollbars wont hide, if i set the target-element to display=none ($#targetdiv).hide();
The scrollbarcontainer still exists and is visible.
I could live with a workaround to set an id to your surrounding div, but this is actually not supported.
Cause i use more scrolling divs, i cant set ($.slimScrollDiv).hide();
You think you can provide a quick fix?
Would love to use your script, it's perfectly done for my needs :)

Submitted by Bernd (not verified) on Fri, 10/19/2012 - 08:47

scroll not updating scrollbar

Thanks for the great plugin!

I am implementing a custom drop down (to allow images and commands in the list - in addition to option items) and have added slimScroll to the control to scroll the option items. When I click on any part of the control, I am toggling the items and I want the list to scroll back up to the top so that when the user opens the select again, the list show the first option item. I am using the scroll option as defined above ($(element).slimScroll({ scroll: '50px' });) where the value is '0px' and it does in fact scroll the list to the top most item, but the slimScroll scroll bar remains in its original position (as if the list were scrolled to the bottom). It also appears as if trying to scroll the list will also allow the scrollbar to fade out even when the railVisible and alwaysVisible options are set to true.

Submitted by Ed (not verified) on Sat, 10/20/2012 - 20:33

just looking for a fix

Hi,

Is there a way to only show the scroll bar when the items need scrolling?

if you can let me know

Thanks,
Sunny

Submitted by sunny (not verified) on Thu, 10/25/2012 - 19:36

M not able to do this..can

M not able to do this..can anybody do it for me..i need that scrollbar badly..

Submitted by Prachi (not verified) on Tue, 10/30/2012 - 10:33

dropdown

this scroll bar not working on multipal dropdown list. plz find out any one how to work in dropdown

Submitted by Rahul (not verified) on Tue, 11/06/2012 - 19:44

scroll from rail

I want the scroller to reach the position where I click on the rail.this happens in facebook.Can this happen here?

Submitted by Ritesh kumar (not verified) on Wed, 11/07/2012 - 09:05

Rail Click

Hi there,
if the railVisible = true and user clicks on the rail it does not scroll

Submitted by Ramy (not verified) on Wed, 11/07/2012 - 20:58

Configurable minBarHeight

Thanks for this great plugin!
I moved minBarHeight as an option (with 30 for default value), so as to be able to configure it. Could you please change the code accordingly on your side?
Thanks and best regards!

Submitted by Olivier (not verified) on Fri, 11/09/2012 - 10:12

Hello Piotr,

Thanks for this plugin ! I like the style.
I would like to put a fluid height (x%) instead of a pixel value. Is it possible ?

Submitted by etn (not verified) on Sun, 11/11/2012 - 15:56

If I Scroll

Thanks for this awesome plugin! Need a clarification.

Scroll div have a number of li (list). when i click the list, open a detail fixed position div. here if i scroll the slim scroll, how to close the popup div. Ex: like facebook smart feed(rhs).

Thanks in advance dude.

Submitted by Pepe (not verified) on Thu, 11/15/2012 - 11:20

How to disable touchpad's movements

Hi there:),

Thanks for the plugin. Awesome stuff.

I just have one question. How can I disable left and right touchpad's movements. For example, when I want to scroll up - I use two fingers + up. It's ok, the same stuff if I use two fingers + left. Can I disable left and right movements? I just need up & down, I have a horizontal bar and I can scroll it only with "allowPageScroll: true", but it moves some off my ".slimscroll" divs.

Thank you

Submitted by Artem (not verified) on Mon, 11/19/2012 - 12:56

Extendable Content

First of all, great plugin! Thanks for it!

I am using the plugin with many different DIVs and it is working great.

But now, I am using a DIV with a stream in it (like facebook-stream), so if the user scrolls to the bottom of the DIV it is extended with more content (jQuery append / AJAX). Using slimScroll here does not work well, because the position of the scrollbar is not updated when extending the DIV. Is there a possibility to use it even so?

Submitted by Stephan (not verified) on Mon, 11/26/2012 - 11:12

IE10 Problem

this scrollbar not working in IE10, can u find any one. why are not working

Submitted by Rahul (not verified) on Tue, 11/27/2012 - 12:20

Not working in IE10

not working in 1E10 any one find.

Submitted by Rahul (not verified) on Tue, 11/27/2012 - 12:23

Drop down menu or listbox scroll not working with in slimscroll

Hi,

Thanks for your script. Really its very helpful for our project.
But one small issue on that.

We have lot of drop down menu and list boxes within the slimscroll content.
But within the slimscroll the drop down menu and list boxes scroll not working.
When we scroll within the list box or drop down menu the content of slimscroll has only scroll that boxes scroll not working..

Please help us to solve this issue!

Thanks

Submitted by Prabu (not verified) on Wed, 11/28/2012 - 12:27

Up/Down Keys don't scroll when focus on scrollable area.

they should, shouldn't they?

Submitted by Chris (not verified) on Thu, 11/29/2012 - 09:09

Slimscroll issue

I have slim scroll in my web page if I put the alert inside the slim scroll it is calling twice in the page.

Submitted by Rohit (not verified) on Wed, 12/05/2012 - 11:17

TypeError: c.draggable is not a function

i keep getting the same error bcos of using ajax load

Submitted by Muhaimin (not verified) on Fri, 12/07/2012 - 06:55

i cant use multiple time in single page.

i cant use multiple scroll with different div in single page.

Submitted by murali (not verified) on Fri, 12/07/2012 - 07:51

Very Easy to Use :)

i like it, great solution, good luck man.

my IE8 return (not minimized code) 'position().top' is null or not an object...
you miss remove '()' :)
fixed : scrollContent($(o.start).position.top, null, true);

Submitted by agL (not verified) on Sat, 12/08/2012 - 15:04

thanks mate

I'll investigate this issue asap and push a new patch.

thanks!

Submitted by Piotr Rochala on Mon, 12/10/2012 - 10:13

Changing the background color of this widget

Hi - If I have to change the background color of the widget (scrollable area), how can I do it please?

Pat

Submitted by Patrick (not verified) on Sun, 12/23/2012 - 22:47

Hi Pat,

slimScroll supports chained jQuery methods, so it should be as easy as $('#mydiv').slimScroll().css('background', 'red');

Submitted by Piotr Rochala on Tue, 12/25/2012 - 00:15

Thanks Works fine

Submitted by Patrick (not verified) on Tue, 12/25/2012 - 15:13

min-height

How i set min-height.

Submitted by anar (not verified) on Tue, 12/25/2012 - 19:35

Scroll Bar

This is great..This is what I'm looking for..

Thanks,

Submitted by John Elli (not verified) on Wed, 12/26/2012 - 05:40

Min height problem

How to i set min height

Submitted by anar (not verified) on Wed, 12/26/2012 - 11:17

slimScroll with allowed page scroll

Hi, I had a problem with slimScroll, when using "allowPageScroll : true". First it would work as expected, scrolling ( w/ mosuewheel) to the top or bottom of the div, and then continue to scroll native page scroller. But after that it would scroll both, slimScroll and native scrollbar of the page (noticed with slimScroll v0.6.5 on Chrome v23).

Upon check i noticed that variable which controlled it ("releaseScroll") would first be set to false, and then to true, but without reverting back to false when again inside of the slimScroll area.
To solve this i added a small piece of code to "_onWheel" function, just after "scrollContent()" function call:

if( o.allowPageScroll && ( percentScroll < 1 && percentScroll > 0 ) ) {
releaseScroll = false;
}

I haven't noticed in comments anybody mentioning this problem, so I won't exclude some special circumstances on my part that may have led to this problem, but if anybody else had a similar problem this could be their solution.

Submitted by Johnny Blue (not verified) on Sat, 01/05/2013 - 22:08

Destroy method

Hi,

great script! What about a destroy handler?

I currently use the following:
$('.slimScrollDiv').contents().unwrap();
$('.slimScrollBar').remove();
$('.slimScrollRail').remove();
$(element).css("height","");

Thanks,
Lukas

Submitted by Lukas (not verified) on Sat, 01/12/2013 - 18:22

Thanks

Thanks u, that's what I want!!

Submitted by Lucas (not verified) on Fri, 01/18/2013 - 18:08

Great plugin....

Very good effor sir, thanks a lot for the plugin.

Submitted by Sanjay (not verified) on Tue, 01/15/2013 - 04:42

Fails with jQuery 1.9.0

The examples in the latest download are using jQuery 1.9.0 and this causes an error if you drag the scroll thumb up/down. I believe you are using "browser." and that is no longer supported in jQuery 1.9.0.

Submitted by Mike (not verified) on Tue, 01/22/2013 - 18:22

thanks Mike - indeed it's a

thanks Mike - indeed it's a mistake. I've updated the code to use jQuery 1.9.0 but I didn't update jQuery UI which slimScroll also needs. And because old version of jQuery UI is not compatible with new jQuery you were seeing an error.

Submitted by Piotr Rochala on Thu, 01/24/2013 - 12:55

fadeout time

FIrst off. thank you so much. this script is golden.

question - is there the ability to change the sensitive of the fadeOut? e.g. make it fade out faster after cursor moves out of the scrollarea.

Submitted by cliff (not verified) on Wed, 01/23/2013 - 05:39

auto or percentage height

Is it possible to get the plugin to scale with it's parent container? I have auto height div with max height of 250px but setting 100% simply shows all text available.

Submitted by Dominic (not verified) on Wed, 01/23/2013 - 23:32

Hi Dominic - you can use

Hi Dominic - you can use height: 'auto' - it will allow slimscroll to take the height of the parent element. See height-width.html from the examples folder for reference. Make sure you are running latest - 1.0.6 version.

Submitted by Piotr Rochala on Thu, 01/24/2013 - 13:00

Add more oprions

Hi Piotr,

Thank you for this awesome plugin, it's small and it works on mobile now, that made me rethink on using custom scrollbars again.

IMHO I believe that it needs more options, like the z-index which is compulsory for such a plugin, I want to be able to set it above a fixed menu without needing to modify a toolkit CSS files or override them.

Next it will be great if you could make it listen for a scroll event and update the scrollbar (handle) position with an animation without hiding the scrollbar, which is happening right now if you try to scroll to a position.

And my final idea for you is to apply distance on top and bottom too, I'm using it right now on a 100% height&width div with overflow hidden and I'm not able to set margins or padding on it to move the scrollbar away from the browser window margins.

I did some changes for z-index and distance and it works but I'm not a master to find a solution for auto-update scrollbar position when an external trigger scrolls the window or overflown element.

Thank you so much for your work, probably soon the whole internet will owes you a beer.

Submitted by RM (not verified) on Sun, 01/27/2013 - 23:29

Mousewheel scrolling outside the slim scroll's div

I love this plugin, but now, i would want to scroll the div "affected" with the mousewheel but outside this one. (Sorry for my bad english). In other words: i have a div (the main div) which has a width of 562px and it's on the center of the webpage, so to scroll it up and down (with the mouse wheel) i have to hover the mouse in that div. To sum up, i want to scroll the div with the mouse wheel outside this one (the div).

You can see what i'm saying on: http://facu_mg.byethost3.com/

Thank you!

Submitted by Charlie (not verified) on Fri, 02/01/2013 - 04:34

Having issues when applying scroll on parent and child element.

Hello Rochal, You created a great plugin but i am having a problem. What i am doing is i am applying scroll on a full page and also applying scroll inside that page on a div. when i am trying to scroll throught that div then it scrolls the page scroller first and not the div scroller. So having issues in applying scroller on a parent div as well as child div where it scrolls the parent scroller first even if we try to scroll the child scroll using mouse wheel. Can you tell me any solution so child scroll should run first if we scroll child and then parent. Any help would be appreciated.

Thanks
Ravinder

Submitted by Ravinder Singh (not verified) on Tue, 02/05/2013 - 08:18

rail click

A user previously entered this question but I do not see an answer. Is there a setting that will let the user click the rail and it will scroll up or down ?

Thanks

Submitted by Roger Jones (not verified) on Wed, 02/06/2013 - 14:53

some improvements ideas

Hi, first of all, it is a great plugin! Congratulation!

I ran into some issues, and maybe you can be inspirated by some new improvements.

1. Multiple scrollable elements with slimScroll, when they are "inside of each other". I have created a stack overflow question of this problem, with a demo page illustrated the problem, please see details in the following link:
http://stackoverflow.com/questions/12930959/multiple-scrollable-elements-with-slimscroll

2. There should be a destroy method, it would be really useful!

3. There ars some problems with textarea when applying slimscroll on it, can be repro on the demo page which is attached to the stack overflow question.

4. Rail click is also would be useful, and maybe you can think the idea, what facebook did, when hovering on the hidden rail, it becomes visible. This might be an option too.

5. Finally when a content is refreshed by ajax datas, the scrollbar could not refresh its position.

Thank you if any above them would be done, and make slimscroll perfect among the custom scrollbars family! :)

Submitted by Se7en (not verified) on Sun, 02/10/2013 - 13:48

Option "opacity" not documented

Hi there,
first of all thanks for the great plugin. I wanted to change the opacity from default 0.4 to a higher value, but couldn't find it here documented .. so I just tested it and it worked by chance :-)
Perhaps you should add it here so everybody knows :)

Submitted by Simon (not verified) on Sat, 02/16/2013 - 14:58

invalid 'in' operand options

slimScroll("destroy");

TypeError: invalid 'in' operand options

change to:
//else if ('destroy' in options)
else if (options.indexOf('destroy'))

thx

Submitted by kandiraton (not verified) on Fri, 02/22/2013 - 07:20

Visibillity

Hi, is there a way to set scrollbar hidden when content is shorter than container?
Right now is always visible.
Thanks for help

Submitted by Peter_D (not verified) on Sat, 02/23/2013 - 12:21

multiple scrolls

Hey,

Thanks for the Plugin.

I do have an issue though with multiple scroll panes.
If you select multiple divs in your selector and then call the slimScroll method, the second div inherits the height of the first one. This also happens for other properties.
This iss because the 'o' object is not properly reset in the each-loop.
moving this line:

var o = $.extend(defaults, options);

into the each-loop solvd the problem, thought you might wanna know.

grtz, Lander

Submitted by Lander (not verified) on Thu, 03/07/2013 - 12:27

Window scoll is not working when navigate to other page

First when i move a mouse in the scrollable area it's scrolling, when navigate to other page, now also window scroll is not working.

variable isOverPanel remains true in _onWheel function.

Submitted by Madhan (not verified) on Fri, 03/15/2013 - 11:51

jQuery slimScroll

What is slimScroll?

Download

Set up

Examples

Documentation

Events

Share

Comments

Pages

Comment

Plain text

Check out my latest game!

Follow me

Recent comments

Recent Articles

What's going on?

Contact Me