HoverScroll jQuery Plugin

Welcome to the HoverScroll jQuery plugin homepage!

This plugin makes an html unordered list [<ul>] scrollable just by hovering the mouse over it. Try it out!

You can also visit the jQuery HoverScroll plugins page or view the evolution at the HoverScroll Google code page

And now, just a quick sample of what HoverScroll really does :

Horizontal Hover Scroll

This example uses all the default parameters.

Vertical Hover Scroll

This is a vertical list example with fixed arrows.

Learn to use HoverScroll now! see the documentation

HoverScroll documentation

To be able to use the HoverScroll plugin you must first include the script and css in the head section of your page along with the jquery library.

	<html>
	<head>
		...
		<link type="text/css" rel="stylesheet" href="jquery.hoverscroll-0.1.0.css" />
		
		<script type="text/javascript" src="jquery.js"></script>
		<script type="text/javascript" src="jquery.hoverscroll-0.1.0.js"></script>
		...
	</head>
	...
	

Then, you will need some html markup:

	<ul id="my-list">
		<li style="width:67px; height:50px;"><img src="images/maja1_th.jpg" /></li>
		<li style="width:67px; height:50px;"><img src="images/maja2_th.JPG" /></li>
		<li style="width:67px; height:50px;"><img src="images/maja3_th.JPG" /></li>
		<li style="width:67px; height:50px;"><img src="images/maja4_th.JPG" /></li>
	</ul>
	

Note for horizontal HoverScrolls:
The width and height is specified on each list item because if the images are not loaded as fast as the code (which happens often) the script cannot reliably determine the width of the content.
When this happens only one item is shown from the list. Generating HoverScrolls upon the window.onload event within a 10ms setTimeout call and specifying the width and height of each item (in the html or in a separate css file) can resolve this problem. The sample above was generated by a php script which determines each images width and height and prints it out in the html, but it is abit useless in this example as all the images have the same size.


Finally, in the head again (after including the scripts) add the following block of code to generate the HoverScroll and you're all good to go!
This creates a horizontal hover scroll list (see further down for default parameters control).

	<script type="text/javascript">
	$(document).ready(function() {
		$('#my-list').hoverscroll();
	});
	</script>
	

View the complete source of this example
	<html>
	<head>
		<link type="text/css" rel="stylesheet" href="jquery.hoverscroll-0.2.0.css" />
		
		<script type="text/javascript" src="jquery-1.3.2.js"></script>
		<script type="text/javascript" src="jquery.hoverscroll-0.2.0.js"></script>
		
		<script type="text/javascript">
		$(document).ready(function() {
			$('#my-list').hoverscroll();
		});
		<script>
	</head>
	<body>
	
	<ul id="my-list">
		<li style="width:67px; height:50px;"><img src="images/maja1_th.jpg" /></li>
		<li style="width:67px; height:50px;"><img src="images/maja2_th.JPG" /></li>
		<li style="width:67px; height:50px;"><img src="images/maja3_th.JPG" /></li>
		<li style="width:67px; height:50px;"><img src="images/maja4_th.JPG" /></li>
		<li style="width:67px; height:50px;"><img src="images/maja5_th.JPG" /></li>
		<li style="width:67px; height:50px;"><img src="images/maja6_th.JPG" /></li>
		<li style="width:67px; height:50px;"><img src="images/maja7_th.JPG" /></li>
		<li style="width:67px; height:50px;"><img src="images/maja8_th.JPG" /></li>
		<li style="width:67px; height:50px;"><img src="images/maja9_th.JPG" /></li>
		<li style="width:67px; height:50px;"><img src="images/maja10_th.JPG" /></li>
	</ul>
	
	</body>
	</html>
	

Plugin reference

$('selector').hoverscroll( [ params {Object} ] );

params {Object}
List of parameters that define the shape and behaviour of the list

	{
		vertical: false,	// Display the list vertically or horizontally
		
		width:    400,		// Width of the list container
		height:   50,		// Height of the list container
		
		arrows:   true		// Display direction indicator arrows or not
		arrowsOpacity: 0.7	// Max possible opacity of the arrows
        fixedArrows: false  // Fixed arrows on the sides of the list (disables arrowsOpacity)

        rtl:      false     // Print images from right to left
		
		debug:    false     // Debug output in the firebug console
	}
	

$('selector')[0].startMoving( direction {int}, speed {int} );

Start moving the list dynamically. Most common use is to execute this method in the window.onload event.

direction {int}
Direction of the movement.

  • 1 : Move towards the bottom/right of the list
  • 0 : Stay still
  • -1: Move towards the top/left of the list

speed {int}
Speed of the movement, which is implemented by the following equation : Displacement = speed * direction

    // Generate hoverscroll with default parameters
	var myList = $('#my-list').hoverscroll();
    
    // Start moving list automatically
    myList[0].startMoving(1, 2);
	

$('selector')[0].stopMoving();

Stop moving the list dynamically. It simply re-initializes the direction and speed to zero.


$.fn.hoverscroll.params

These are the HoverScroll default parameters. It can be very useful to override these so you don't have to specify parameters for each HoverScroll call.

For example:

	// Override default parameters onload
	$.fn.hoverscroll.params = $.extend($.fn.hoverscroll.params, {
		vertical : true,
		width: 67,
		height: 300,
		arrows: false
	});
	
	// Generate hoverscroll with overridden default parameters
	$('#my-list').hoverscroll();
	

Generated markup

Here is a sample of markup generated by hoverscroll (note: you must not use this markup in your code or else HoverScroll will not work properly) :

	<div class="ui-widget-content hoverscroll horizontal">
		<div class="listcontainer">
			<ul id="my-list" class="list ui-helper-clearfix">
				<li class="item"><img src="images/maja1_th.jpg" /></li>
				<li class="item"><img src="images/maja2_th.JPG" /></li>
				<li class="item"><img src="images/maja3_th.JPG" /></li>
				<li class="item"><img src="images/maja4_th.JPG" /></li>
				<li class="item"><img src="images/maja5_th.JPG" /></li>
				<li class="item"><img src="images/maja6_th.JPG" /></li>
				<li class="item"><img src="images/maja7_th.JPG" /></li>
				<li class="item"><img src="images/maja8_th.JPG" /></li>
				<li class="item"><img src="images/maja9_th.JPG" /></li>
				<li class="item"><img src="images/maja10_th.JPG" /></li>
			</ul>
			<div class="arrow left"></div>
			<div class="arrow right"></div>
		</div>
	</div>
	

As you can see, HoverScroll integrates with the jQuery UI by implementing one of its CSS classes.

Download the HoverScroll jQuery plugin

Filename Description Version Size Release Date Download
jquery.hoverscroll-0.2.4.zip Added rtl option 0.2.4 24.3 KB 20-02-2011 3:19pm Download 0.2.4
jquery.hoverscroll-0.2.3.zip Added options 0.2.3 23.2 KB 09-12-2010 11:31pm Download 0.2.3
jquery.hoverscroll-0.2.2.zip Bug fixes 0.2.2 23.2 KB 20-09-2009 11:19am Download 0.2.2
jquery.hoverscroll-0.2.1.zip Bug fixes 0.2.1 22.22 KB 17-07-2009 16:55pm Download 0.2.1
jquery.hoverscroll-0.2.0.zip Added some features 0.2.0 47.44 KB 29-06-2009 9:49pm Download 0.2.0
jquery.hoverscroll-0.1.1.zip Minor bug fix 0.1.1 2.2 KB 27-06-2009 6:00pm Download 0.1.1
jquery.hoverscroll-0.1.0.zip First release of the plugin 0.1.0 2.2 KB 26-06-2009 9:05pm Download 0.1.0

HoverScroll Changelog

HoverScroll 0.2.4 :: 20-02-2011 3:19pm

  • Added "Right to Left" option, only works with horizontal lists
  • Optimization of arrows opacity control (Thanks to Josef Körner)

HoverScroll 0.2.3 :: 09-12-2010 11:31pm

  • Added fixed arrows option
  • Binded startMoving and stopMoving functions to the HoverScrolls HTML object for external access

HoverScroll 0.2.2 :: 20-09-2009 11:19am

  • Backward compatibility with jQuery 1.1.x (Arrow opacity bug remaining)
  • Added test file to the archive
  • Bug fix: The right arrow appeared when it wasn't necessary (Thanks to <admin at unix dot am> for finding the fix for this)

HoverScroll 0.2.1 :: 17-07-2009 16:55pm

  • Backward compatibility with jQuery 1.2.x (thanks to Andy Mull for compatibility with jQuery >= 1.2.4)
  • Added information to the debug log
  • Suppressed subversion tracking files, greatly reduced the files size (duh..)

HoverScroll 0.2.0 :: 29-06-2009 9:00pm

Added some new features

  • Direction indicator arrows
  • Permanent override of default parameters
note: This version is alot larger because images are now included with the script, some images are not used by default.

HoverScroll 0.1.1 :: 27-06-2009 6:00pm

Minor bug fix

  • Hover zones did not cover the complete container
note: The css file has not changed therefore it is still versioned 0.1.0


HoverScroll 0.1.0 :: 26-06-2009 9:05pm

First release of the plugin. Supports:

  • Horizontal and vertical lists
  • Width and height control
  • Debug log (doesn't show useful information for the moment)

HoverScroll license

FREE BEER LICENSE VERSION 1.02

The free beer license is a license to give free software to you and free
beer (in)to the author(s).

Your rights are :

0. You can use this piece of software in anyway you like.

1. You can redistribute this piece of software in source form or in 
   compiled form. 

2. You can alter the source to your needs and redistribute the altered 
   source in source form or in compiled form.

However :

0. This program is provided without warranty of any kind. So, if it 
   breaks anything, for example itself, it is up to you. 

1. If you redistribute this piece of software, you are not allowed to 
   charge money for this piece of software itself.

2. If you redistribute this pieces of software in binary form, you must 
   supply the source code as well.

3. If you redistribute this software, modified or not, you must 
   redistribute it under this license and you must include the name of 
   the original author(s) and you must point out where the original 
   source can be obtained.

4. If you use this piece of software frequently, and you think it is 
   worth a couple of euros, you are not allowed to send the author 
   anything else than beer or means that provide facilities to get beer 
   into the author(s) (i.e. openers, glasses).

Bookmark and Share
Author: RasCarlito <carl.ogren@gmail.com>