Smooth Div Scroll is a jQuery plugin that scrolls content horizontally left or right. Apart from many of the other scrolling plugins that have been written for jQuery, Smooth Div Scroll does not limit the scroling to distinct steps. As the name of the plugin hints, scrolling is smooth. There are no visible buttons or links since the scrolling is done using hot spots within the scrollable area or via autoscrolling. Unobtrusive and smooth is the key here.

Table of contents

1. How it works
   • Scrolling using the hot spots
   • Autoscrolling
2. Quick demo
3. Key features
4. More examples!
   • Scrolling text
   • Small scroller
   • Running ticker
   • Clickable logo parade
   • Ping-pong scroller
   • Multiple autoscrollers on one page (loading content through AJAX)
5. Parameters
6. The CSS
7. Dependencies
8. Download
9. Help and support
10. Newsletter
11. FAQ
12. Version history
13. To-do (the next version)
14. Copyright, license and all that
15. About me
16. Do you want to help or give it a rating?

How it works

Smooth Div Scroll works by scrolling one div (scrollableArea) inside another div (scrollWrapper). Ether two hotspot div's are used to trigger the actual scrolling (scrollingHotSpotLeft and scrollingHotSpotRight) or you can let it autoscroll.

The scrollWrapper determines how much of the scrollableArea div that should be visible - everything outside the scrollWrapper is hidden from the user. The scrollWrapper is always placed inside a containing div and it's upon this containing div that we apply the Smooth Div Scroll plugin. The containing div also determines the width and height. Then the width of scrollWrapper is set to 100%, giving it the same width as the containing element.

You are in full control of the scrolling behavior. The scrolling can be controlled using the hot spots, or you can disable the hot spots alltogether and just let it autoscroll - like a running ticker or slideshow. There's also a mixed mode where Smooth Div Scroll will autoscroll as long as the user does not interact with the scroller (use the hot spots). As soon as the user moves the pointer over one of the hot spots, the autoscrolling will stop and the user takes control of the scrolling. The mixed mode is excellent for showing the user that there is a part of the page that is scrollable and if you combine it with having visible hot spots for the first 10-15 seconds after the page has loaded, your users will instinctively understand how to interact with the scroller.

Scrolling using the hot spots

Moving the mouse pointer over scrollingHotSpotLeft makes the scrollable area move to the right, giving the impression that the user is scrolling left. Moving the mouse pointer over scrollingHotSpotRight makes the scrollable area move to the left, giving the impression that the user is scrolling right.

Autoscrolling

As I've mentioned earlier, autoscrolling comes in two flavors:

• onstart - initial autoscroll until the user interacts with the scroller by moving the pointer over one of the hot spots. After that all scrolling has to be done using the hot spots.
• always - no user interaction (hot spots are disabled) and the scrolling is controlled only by the parameters you've set for autoscrolling.

Speed is controlled using the parameter autoScrollSpeed. A speed of 1-2 is slow, 3-4 is medium, 5-13 is fast and anything higher is superfast. Then there is direction and certain scrolling beaviors. This is controlled using the parameter autoScrollDirection. You can choose between four different settings:

• right - autoscrolls right and stops when it reaches the end.
• left - autoscrolls left and stops when it reaches the end. (Setting the autoScrollDirection to "left" is only relevant if you use the parameter startAtElementId and set it to something other than the first element.)
• backandforth - starts autoscrolling right and when it reaches the end, switches to autoscrolling left and so on. Scrolling ping-pong style.
• endlessloop - continuous scrolling right - an endless loop of elements. When the scroller reaches the last element the first will appear and so on in a never-ending loop.

Even if you have set autoscroll to always, it's nice to give the user the option to stop the scrolling momentarily if there is something that he/she wants to take a longer look at. The parameter pauseAutoScroll is the one you'll use for that. Choose between the values mousedown and mouseover or just leave it blank for no pausing possibilities. If you choose mousedown autoscrolling will pause as long as the user holds down the mouse button while the pointer is over the scroller. If you choose mouseover, the user only needs to move the pointer over the scroller to pause the autoscrolling. When the pointer exits the scroller, autoscrolling will continue.

Quick demo

Here's a quick demo of Smooth Div Scroll in action. The jQuery code for this demo looks like this:

<script type="text/javascript">
		$(function() {
			$("div#makeMeScrollable").smoothDivScroll({scrollingSpeed: 12, mouseDownSpeedBooster: 3, autoScroll: "onstart", autoScrollDirection: "endlessloop", autoScrollSpeed: 2, visibleHotSpots: "onstart", hotSpotsVisibleTime: 9, startAtElementId: "startAtMe"});
		});
</script>

I've set some parameters that are not default for this demo:

• A somewhat slower scrolling speed than the default speed (scrollingSpeed: 12).
• A speed boost so the scrolling will go three times as fast if the user presses the mouse button while inside one of the scrolling hot spots (mouseDownSpeedBooster: 3).
• Set the autoscrolling to "onstart" (autoScroll: "onstart") so I get autoscrolling until the user uses one of the hot spots.
• I want the autoscrolling to be an endless loop (autoScrollDirection: "endlessloop").
• Custom autoscrolling speed (autoScrollSpeed: 2).
• Set the parameter for making the hot spots visible on start and a custom number of seconds that I want them to be visible (visibleHotSpots: "onstart" and hotSpotsVisibleTime: 9). This means the hot spots will be visible for 9 seconds after the page has loaded and then disappear. (If you don't see them, it's probably because they have disappeared before you got down to this section of the page.)
• Set the parameter for starting at a specific element inside the scrollable area. In this case I've given the element that I want to start at the id "startAtMe".

The result is this:

In the demo above the XHTML-code looks like this:

<div id="makeMeScrollable">
	<div class="scrollingHotSpotLeft"></div>
	<div class="scrollingHotSpotRight"></div>
	<div class="scrollWrapper">
		<div class="scrollableArea">
			<img src="images/demo/image_1.jpg" alt="Demo image" />
			<img src="images/demo/image_2.jpg" alt="Demo image" />
			<img src="images/demo/image_3.jpg" alt="Demo image" id="startAtMe" />
			<img src="images/demo/image_4.jpg" alt="Demo image" />
			<img src="images/demo/image_5.jpg" alt="Demo image" />
		</div>
	</div>
</div>

As you can see there is a surrounding div with the id makeMeScrollable. This is the element that I turn into a Smooth Div Scroll. You can also see the element that I've given the ID startAtMe so I can tell Smooth Div Scroll that I want it to start the scrolling at this element using the parameter startAtElementId: "startAtMe".

The jQuery code looks like this:

$(function() {
	$("div#makeMeScrollable").smoothDivScroll({scrollingSpeed: 12, mouseDownSpeedBooster: 3, autoScroll: "onstart", autoScrollDirection: "endlessloop", autoScrollSpeed: 2, visibleHotSpots: "onstart", hotSpotsVisibleTime: 9, startAtElementId: "startAtMe"});		
});

In this example I've used many of the available parameters. You'll find all the parameters described here.

Please note that you may have to give the elements that you put inside the scrollable area some styling to make sure that they are positioned like you want them. In the demo above I want all the images on a single row, one after the other, with no margin or padding. So I add a style to my CSS that looks like this:

	#makeMeScrollable div.scrollableArea *
	{
		position: relative;
		float: left;
		margin: 0;
		padding: 0;
	}

If you skip this, it might still work but it's good practice to always style the elements inside scrollableArea to make sure the behave like they are supposed to. For example, if you remove the above styling from this demo, an "invisible" space will be added between the images (assuming you keep the tags on separate lines in the code). By invisible I mean that the space is visible in the browser window but none of the jQuery functions will recognize and include this space in the total width calculation. Needless to say, this confuses the function that calculates the total width and the result is often that there is not enough room for the last element and it is not shown. By floating all images and removing all padding and margin I prevent this error.

Key features

Here are some of the key features that I've incorporated into the design. They are not parameters or other settings but rather basic design principles and behaviors:

• Scrolling hot spots that are activated and deactivated depending on if they are needed or not. For example, if you have scrolled as far to the right as possible, scrollingHotSpotRight becomes inactive (hidden) and vice versa with scrollingHotSpotLeft. Another example: if the width of scrollableArea is equal to or shorter than scrollWrapper, both scrolling hot spots become inactive - obviously.
• The scrolling speed varies depending how far left or right you move the mouse pointer inside the hot spot.
• You should be able to put any element into the scrollable area as long as its width and height can be calcuated since Smooth Div Scroll does a lot of calculations using the width and height of the elements inside it. If you are experiencing problems with this you can try wrapping your elements in div's or set the element display to block in the CSS.

More examples!

Here are some more examples of how SmoothDivScroll can be used. If you have cool examples of how you have used SmoothDivScroll, please drop me an email with the URL.

• Scrolling text
• Small scroller
• Running ticker
• Clickable logo parade
• Ping-pong scroller
• Multiple autoscrollers on one page (loading content through AJAX)

Parameters

Here are the parameters that can be supplied as arguments to the plugin. You can always leave all parameters out. Smooth Div Scroll will then use the default values.

The CSS

There is a CSS that accompanies the Smooth Div Scroll jQuery plugin. It looks like this:

/*	Invisible left hotspot */
div.scrollingHotSpotLeft
{
	/* 	The hotspots have a minimum width of 100 pixels 
	and if there is room the will grow and occupy 15% 
	of the scrollable area (30% combined). Adjust it 
	to your own taste. */
	min-width: 75px;
	width: 10%;
	height: 100%;
	/*	There is a big background image and it's used 
		to solve some problems I experienced
		with Internet Explorer 6. */
	background-image: url(../images/big_transparent.gif);
	background-repeat: repeat;
	background-position: center center;
	position: absolute;
	z-index: 200;
	left: 0;
	/*  The first url is for Firefox and other browsers, the second is for Internet Explorer */
	cursor: url(../images/cursors/cursor_arrow_left.cur), url(images/cursors/cursor_arrow_left.cur),w-resize;
}

/*	Visible left hotspot */
div.scrollingHotSpotLeftVisible
{
	background-image: url(../images/arrow_left.gif);				
	background-color: #fff;
	background-repeat: no-repeat;
	opacity: 0.35; /* Standard CSS3 opacity setting */
	-moz-opacity: 0.35; /* Opacity for really old versions of Mozilla Firefox (0.9 or older) */
	filter: alpha(opacity = 35); /* Opacity for Internet Explorer. */
	zoom: 1; /* Trigger "hasLayout" in Internet Explorer 6 or older versions */
}

/* Invisible right hotspot */
div.scrollingHotSpotRight
{
	min-width: 75px;
	width: 10%;
	height: 100%;
	background-image: url(../images/big_transparent.gif);
	background-repeat: repeat;
	background-position: center center;
	position: absolute;
	z-index: 200;
	right: 0;
	/*  The first url is for Firefox and other browsers, the second is for Internet Explorer */
	cursor: url(../images/cursors/cursor_arrow_right.cur), url(images/cursors/cursor_arrow_right.cur),e-resize;
}

/* Visible right hotspot */
div.scrollingHotSpotRightVisible
{
	background-image: url(../images/arrow_right.gif);
	background-color: #fff;
	background-repeat: no-repeat;
	opacity: 0.35;
	filter: alpha(opacity = 35);
	-moz-opacity: 0.35;
	zoom: 1;
}

/*	The scroll wrapper is always the same width and 
	height as the containing element (div). Overflow 
	is hidden because you don't want to show all of 
	the scrollable area.
*/
div.scrollWrapper
{
	position: relative;
	overflow: hidden;
	width: 100%;
	height: 100%;
}

div.scrollableArea
{
	position: relative;
	width: auto;
	height: 100%;
}

Dependencies

Smooth Div Scroll depends heavily on the hard work of another plugin developer so you can't run it unless you have the jquery.scrollTo plugin.

Also you will need the latest version of jQuery. In this example I'm using 1.3.2.

Download

Download a zip-file with the latest javascript (full commented source code + a minified version), CSS, cursors and some images. You will also need to download the jquery.scrollTo plugin. Otherwise it will not work.

Download SmoothDivScroll_0-9.zip

Help and support

I receive a lot of emails from people all over the World, asking me questions about Smooth Div Scroll. I really appreciate getting mail but working full time and being a father of two, I simply don't have the time to provide support and help everyone with site-specific questions. Therefore I have created a Google group where users can help each other.

Subscribe to jQuery SmoothDivScroll

Email:

Visit this group

Please turn to this group for help and support.

Newsletter

I send an email to all my smooth scrolling friends whenever there's a new version of Smooth Div Scroll. Sign up if you want to know when there's a new version. I promise I won't spam you with lot's of stuff - just useful info and not very often.

FAQ

If you have any questions, please turn to the jQuery SmoothDivScroll Google group.

<script type="text/javascript">
  $(document).ready(function(){
   
    $("a").live("mouseover", function(){
      $(this).fancybox();
    });

  });
  </script>

Version history

To-do (the next version)

Altering the cloning action when scrolling in an endless loop. The problem is that the new cloned elements don't get their events bound as they're cloned. You can use .live as a fix for this, but as Paul Shapiro kindly pointed out, a simpler solution is to use clone(true). This way it will also clone the event handlers bound to the elements.

Martin Schubert reported problems when replacing the content of the scrollable area using AJAX after the page had loaded - Smooth Div Scroll doesn't recalculate the scrollable area. The recalculation is done first when the user resizes the browser window. Looking at the source code there's a function called "windowIsResized". This is triggered when the user resizes the browser window and it (among other things) properly recalculates the width of the scrollable area. The code should be rewritten with a general function that "reinitializes" the scroller. This function should be a part of the public API so it can be called by the developer after an AJAX content load has been done.

Vincent Weber wrote me regarding the cursors and the fact that the custum cursors are not shown in Internet Explorer. The problem has to do with relative URL's. The URL that is relative to the CSS is used by Firefox and other browsers and looks like this:

// Firefox cursor URL
cursor: url(../images/cursors/cursor_arrow_right.cur), w-resize;

Internet Explorer on the other hand wants you to use the HTML sourse file as the base of the URL, not the CSS. An example of an Internet Explorer URL would be:

// Internet Explorer cursor URL
cursor: url(images/cursors/cursor_arrow_right.cur), w-resize;

If you want it to work in both Internet Explorer, Firefox and other browsers you simply supply both URL's, like this:

// Cursor URL for both Internet Explorer and other browsers
cursor: url(../images/cursors/cursor_arrow_right.cur), url(images/cursors/cursor_arrow_right.cur),w-resize;

Vincent also sent a reference regarding custom cursors for anyone who wants to read more. This cursor CSS is implemented in the demo on this page.

Konstantin Hidirov found a solution to the problem with setting slower scrolling speeds and was kind and sent me an email with his example. A solution along his lines will be implemented in the next version, but for those of you who want to fix it right now, here's an example:

1) Place this code at the beginning of plugin file

window.splitterValue = 1;

function splitter(cnt) {
  window.splitterValue++;
  var r = (window.splitterValue > cnt);
  if (r) window.splitterValue = 1;
  return r;
}

This function returns TRUE in 1/cnt cases.

2) Then, put the next line into the main routine. I used "backandforth" mode and placed it so:

....
case "backandforth":
    if (!splitter(3)) return;
....

Now the speed of animation will be 1/3. As Konstantin points out, the code might need some cleaning and it needs to be properly tested and integrated into the plugin, but this will do for now.

Copyright, license and all that

Copyright © 2010 Thomas Kahn - thomas(at)karnhuset(dot)net

This plugin is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or any later version.

This plugin is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

About me

My name is Thomas Kahn and I live and work in Stockholm, Sweden. I've been working as a web developer for the past thirteen years. Currently I'm working at a small advertising agency called Kärnhuset in central Stockholm. When I'm not dabbling with jQuery I program in ASP.NET/C#, XML/XSLT and I also do a lot of XHTML/CSS. Umbraco is my favorite CMS and I try to be as active as I can in the Umbraco community.

Please email suggestions on improvements! This is the first jQuery plugin that I've developed so there must be quite a lot that can be improved: thomas(at)karnhuset(dot)net.

Happy scrolling!

Do you want to help out or give this plugin a rating?

If you found this plugin useful, I would really appreciate it if you could give it a nice rating on my jQuery plugin page. That way more people will find it and use it, which is my goal with this project. On the top of the jQuery plugins page you'll find a star rating widget that enables you to give the plugin a rating. You need to be logged in.

If you are an experienced jQuery plugin developer and want to contribute to make this plugin the best smooth scrolling plugin ever, don't hesitate to drop me an email: thomas(at)karnhuset.net! .